Banking API authentication

The Banking API uses a two-step flow: first you authenticate the customer with email and password, then you exchange the resulting token for a JWT access token that signs every other call.

The three endpoints in the Auth group are the only ones that carry no Authorization header. Every other endpoint requires Authorization: Bearer <access_token>.

Step 1 — Login#

POST /api/public/v1/auth/login

Required body: email (email format) and password.

{
  "email": "operations@merchant.com",
  "password": "••••••••"
}

The 200 response returns in data:

Each assignments item carries assignment_id, owner_type, owner_id, tenant_id, tenant_code, country_code, role, roles and status. Pick the assignment_id of the context you will operate with.

Step 2 — Token exchange#

POST /api/public/v1/auth/token/exchange

Required body: gidp_id_token (from step 1) and assignment_id (the chosen context).

{
  "gidp_id_token": "eyJhbGciOi...",
  "assignment_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

The 200 response returns in data:

claims includes sub, subject_kind, user_type, tenant_id, owner_type, owner_id, roles, scopes, country_code, locale, channel, idp, idp_sub and idempotency_key.

Step 3 — Use the Bearer token#

The declared security scheme is BearerAuth: HTTP bearer with JWT format.

Authorization: Bearer <access_token>

Context travels inside the token: business operations do not take tenant_id, owner_id or owner_type as parameters. The token alone scopes which accounts and payments you can reach.

When the token is absent, expired or invalid, the response is 401 with response_code: UNAUTHORIZED. If the token is valid but the context does not authorize the resource, it is 403 with FORBIDDEN. Repeat step 2 to renew the access token before expires_in elapses.

Passwords#

POST /api/public/v1/auth/request-set-password

Starts the set/reset password process for the given email. It requires no prior authentication and always responds the same way whether or not the account exists, so it never reveals if an email is registered.

{
  "email": "operations@merchant.com"
}