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.
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>'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. |