Skip to content
Developer Portal Karmo Developer Portal

Exchange an IdP idToken for a karmoJWT (no cookies, no persistent state)

POST
/auth/sessions/exchange

Public endpoint. Verifies the supplied IdP idToken (SuperTokens session JWT today; vendor-neutral by iss), resolves the caller’s roles and permissions, and mints a 900s-TTL karmoJWT with aud: ['bff-vouch'] returned in the response body. The FE attaches the returned accessToken as Authorization: Bearer ... on subsequent BFF calls. Until NITRO-1040 (verify) and NITRO-1071 (resolve) land, this endpoint surfaces 503 on every call by design — the placeholder providers fail loudly rather than mint synthetic karmoJWTs.

Request Body required

Section titled “Request Body required ”
object
idToken
required

IdP-issued idToken (SuperTokens session JWT today; the iss claim selects the verification strategy).

string

Responses

Section titled “ Responses ”

200

Section titled “200 ”
object
user
required
object
id
required

User identifier — equal to the IdP sub (also the karmoJWT sub).

string
tenantId
required

Tenant identifier. Hard-coded to karmo during the interim period before NITRO-1039’s real tenant resolver lands.

string
nullable
email

User email, if returned by the IdP.

string
roles
required

Karmo-side roles for the caller (resolved against vouch).

Array<string>
permissions
required

Karmo-side permissions for the caller (resolved against vouch).

Array<string>
expiresAt
required

ISO-8601 instant — the access token’s exp rendered as UTC.

string
accessToken
required

RS256-signed karmoJWT, aud=['bff-vouch'], 900s TTL.

string
expiresIn
required

Access token TTL in seconds (900 by default; honours ACCESS_TOKEN_TTL_SECONDS env override).

number

400

Section titled “400 ”

BAD_REQUEST

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

401

Section titled “401 ”

UNAUTHORIZED

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

403

Section titled “403 ”

FORBIDDEN

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

404

Section titled “404 ”

NOT_FOUND

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

409

Section titled “409 ”

CONFLICT

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

422

Section titled “422 ”

UNPROCESSABLE_ENTITY

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

500

Section titled “500 ”

INTERNAL_SERVER_ERROR

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email