/{app_slug}/v1/auth/oauth/exchangeExchange a `heimdall_code` (received on the web-flow callback redirect) for Auth access + refresh tokens. Single-use.
Path parameters
app_slug*stringSlug of the app.
Request body
code*stringThe opaque `heimdall_code` the customer received on the OAuth callback `return_to`. Single-use; expires after 60 seconds.
Example: "hc_8f14e45fceea167a5a36dedd4bea2543"
Response · 200 Either `{access_token, refresh_token, token_type, expires_in}` (ordinary sign-in) or `{mfa_enrollment_required: true, mfa_token, expires_at}` (the app mandates MFA and the account holds no factor). Branch on `mfa_enrollment_required`.
result*object`session` when tokens were minted, `mfa_enrollment_required` when the app requires MFA and the user must enrol first (the token fields are then absent).
access_tokenstringPresent on the ordinary sign-in outcome. Absent when `mfa_enrollment_required` is true — no session was minted.
refresh_tokenstringLong-lived token that mints a new access token via `refresh`. Rotated on use.
token_typeobjectAlways `Bearer`.
expires_innumberLifetime of the access token in seconds.
mfa_enrollment_requiredobjectSet when the app runs `auth_config.mfa: "required"` and the account holds no enabled factor. NO session was minted; the token fields are absent and `mfa_token` carries the enrolment challenge instead.
mfa_tokenstringEnrolment challenge token. Drive `POST /{app_slug}/v1/auth/mfa/enroll` then `/auth/mfa/enroll/verify` with it to enrol a factor and receive tokens. Session-equivalent — treat it like a refresh token and never place it in a URL.
expires_atstringISO-8601 expiry of `mfa_token` (10 minutes out).
Example
Request
POST https://api.auth.productcraft.co/{app_slug}/v1/auth/oauth/exchange
Content-Type: application/json
{
"code": "hc_8f14e45fceea167a5a36dedd4bea2543"
}Response
{
"result": {},
"access_token": "string",
"refresh_token": "string",
"token_type": {},
"expires_in": 0,
"mfa_enrollment_required": {},
"mfa_token": "string",
"expires_at": "string"
}