Authentication

This page describes the flow for authenticating and obtaining a BagID access token.

A — Login using host federated identity token

Validates federated identity token and returns an access token.

Operation: POST /v2/auth/federated/sessions

Headers

Header Structure St Rep Comments

X-Source-App-Key

String

M

1

Issued client key for request authorization and routing

Authorization

 — 

 — 

 — 

Not used (pre-login)

Body (FederatedLoginRequest)

Field Structure St Rep Comments

token

String

M

1

Trusted JWT from the host app

Request example

{
  "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Responses

200 OK (LoginResponse)

Field Structure St Rep Comments

accessToken

String

M

1

JWT access token

tokenType

String

M

1

e.g. Bearer

expiresIn

Integer (int32)

M

1

Expiry in seconds

refreshToken

String

O

0..1

Refresh token when issued

refreshExpiresIn

Integer (int32)

O

0..1

Refresh expiry in seconds

Example:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 600,
  "refreshToken": "def50200...",
  "refreshExpiresIn": 86400
}

401 UNAUTHORIZED (ErrorResponse)

{
  "status": "401 UNAUTHORIZED",
  "statusCode": 401,
  "message": "Invalid federated token",
  "errorCode": "federated_token_invalid",
  "errors": [
    "Invalid federated token"
  ]
}

B — Attestation login

Attestation login is a two-step process, firstly requiring generating a nonce, then either login as identified app user with email address or as guest.

B-1 — Generate nonce

Operation: POST /v2/auth/nonces

Headers

Header Structure St Rep Comments

X-Source-App-Key

String

M

1

Issued client key

Body

None.

Responses

200 OK (NonceResponse)
Field Structure St Rep Comments

nonce

String

O

0..1

Nonce for attestation flow

expiresAt

String (date-time)

O

0..1

Absolute expiry

ttlSeconds

Integer (int32)

O

0..1

Time-to-live in seconds

Example:

{
  "nonce": "n_abc123def456ghi789",
  "expiresAt": "2026-04-08T12:05:00Z",
  "ttlSeconds": 60
}
400 BAD_REQUEST (ErrorResponse)
{
  "status": "400 BAD_REQUEST",
  "statusCode": 400,
  "message": "Unable to issue nonce",
  "errorCode": "valid_client-key_is_required",
  "errors": [
    "Unable to issue nonce"
  ]
}

B-2a — Login using app attestation and email

Operation: POST /v2/auth/attestation/sessions

Headers

Header Structure St Rep Comments

X-Source-App-Key

String

M

1

Issued client key

Body (AttestationLoginRequest)

Field Structure St Rep Comments

nonce

String

M

1

From POST /v2/auth/nonces

attestationObject

String

M

1

App attestation payload
Request example
{
  "nonce": "n_abc123def456ghi789",
  "attestationObject": "base64-encoded-attestation-object"
}

Responses

200 OK (LoginResponse)

Example:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 600,
  "refreshToken": "def50200...",
  "refreshExpiresIn": 86400
}
401 UNAUTHORIZED (ErrorResponse)
{
  "status": "401 UNAUTHORIZED",
  "statusCode": 401,
  "message": "Invalid attestation",
  "errorCode": "invalid_login_request",
  "errors": [
    "Invalid attestation"
  ]
}

B-2b — Login in guest mode

Operation POST /v2/auth/guest/sessions

Headers

Header Structure St Rep Comments

X-Source-App-Key

String

M

1

Issued client key

Body (GuestLoginRequest)

Field Structure St Rep Comments

nonce

String

M

1

From POST /v2/auth/nonces

attestationObject

String

M

1

App attestation payload
Request example
{
  "nonce": "n_guest_001",
  "attestationObject": "base64-encoded-attestation-object"
}

Responses

200 OK (LoginResponse)

Example:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 600
}
401 UNAUTHORIZED (ErrorResponse)
{
  "status": "401 UNAUTHORIZED",
  "statusCode": 401,
  "message": "Guest session rejected",
  "errorCode": "invalid_login_request",
  "errors": [
    "Guest session rejected"
  ]
}

C — Login for B2B secret-based clients

Login for B2B secret-based clients

Operation POST /v2/auth/b2b-secret/sessions

Headers

Header Structure St Rep Comments

X-Source-App-Key

String

M

1

Issued client key

X-B2B-Secret

String

M

1

B2B shared secret

Body (B2BSecretLoginRequest)

Field Structure St Rep Comments

username

String

M

1

B2B username

password

String

M

1

B2B password

Request example

{
  "username": "airline_service_account",
  "password": "••••••••"
}

Responses

200 OK (LoginResponse)

Example:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 600
}

401 UNAUTHORIZED (ErrorResponse)

{
  "status": "401 UNAUTHORIZED",
  "statusCode": 401,
  "message": "Invalid credentials",
  "errorCode": "invalid_login_request",
  "errors": [
    "Invalid credentials"
  ]
}

Refresh access token

Used to get a new access token using the refresh token.

Operation POST /v2/auth/refresh

Headers

Header Structure St Rep Comments

X-Source-App-Key

String

M

1

Issued client key

Body (RefreshTokenRequest)

Field Structure St Rep Comments

refreshToken

String

M

1

Refresh token from login

Request example

{
  "refreshToken": "def50200refresh..."
}

Responses

200 OK (LoginResponse)

Example:

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 600,
  "refreshToken": "def50200newrefresh...",
  "refreshExpiresIn": 86400
}

401 UNAUTHORIZED (ErrorResponse)

{
  "status": "401 UNAUTHORIZED",
  "statusCode": 401,
  "message": "Invalid or expired refresh token",
  "errorCode": "refresh_token_invalid",
  "errors": [
    "Invalid or expired refresh token"
  ]
}