# Authentication

Our APIs support two authentication patterns. C2B (consumer-to-business) uses the
Yi frontend session for browser-based integrations. B2B (business-to-business) uses
an OAuth access token created by the session service and passed downstream as a
bearer token.

Direct host: `https://interact.hsbc.com`

## C2B — Session-based

Used by browser applications. The session is established after the user completes the
Yi login flow. Provide exactly one of the two credentials below per request.

### Session Cookie

The `neosession` cookie is set automatically by the Yi frontend after login. The
token must carry a non-blank `sub`, `amToken` and `tpid`, otherwise it is rejected
with **401 Unauthorized**.

```
Cookie: neosession=<session_token>
```

### Session Header

An alternative to the cookie for contexts where cookies cannot be set (e.g. local
development tooling or non-browser HTTP clients). The same JWT value is used.

```
X-NIO-Session: <session_token>
```

## B2B — OAuth Bearer Token

Used for server-side and service-to-service integrations. Your client calls the
session service with its registered client credentials, receives a short-lived OAuth
access token, then sends that token to our APIs in the `Authorization` header.

### 1. Create the access token

Request a token from the session service using the OAuth client credentials flow. The
Basic authorization value is the Base64 representation of `client_id:client_secret`;
treat it as a secret and never publish the encoded value in documentation, client-side
code or source control.

```
curl --request POST \
  --url https://interact.hsbc.com/session/oauth/token \
  --header 'Authorization: Basic <base64(client_id:client_secret)>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'grant_type=client_credentials'
```

### 2. Read the token response

The session service returns a bearer token and its lifetime. Cache the token only for
the returned `expires_in` window, then request a new token before it expires.

```
{
  "access_token": "<oauth_access_token>",
  "token_type": "Bearer",
  "expires_in": 300
}
```

### 3. Pass the token downstream

Send the returned access token to downstream APIs as a bearer token. For this B2B
journey, we expect the `Authorization` header only; do not add `x-hsbc-custid` or
`x-hsbc-channel-id` headers.

```
curl --request GET \
  --url https://interact.hsbc.com/<service>/<resource> \
  --header 'Authorization: Bearer <oauth_access_token>'
```

**Important:** Sending a `neosession` cookie **and** an `Authorization` header in the
same request returns **400 Ambiguous authentication credentials**. Use exactly one
credential type per request: a C2B session credential or a B2B bearer token.

## Correlation ID

All APIs accept an optional correlation ID header to trace a request through logs and
downstream services. Include this value in support requests. The header is
auto-generated when not supplied.

| API | Header | Format |
|---|---|---|
| Accounts, Transactions | `hsbc-correlation-id` | Non-blank numeric string. Non-numeric values are ignored and a timestamp-based ID is generated instead. |
| Payments | `X-HSBC-Request-Correlation-Id` | UUID recommended. Forwarded to downstream services and recorded in logs. |

**Important:** Never expose authentication tokens in client-side code or version
control. Use environment variables and secure token storage for all integrations.