Auth API reference

Auth API · Consumer-Oauth-Sign-In

post/{app_slug}/v1/auth/oauth/exchange

Exchange a `heimdall_code` (received on the web-flow callback redirect) for Auth access + refresh tokens. Single-use.

Path parameters

app_slug*string

Slug of the app.

Request body

code*string

The 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_tokenstring

Present on the ordinary sign-in outcome. Absent when `mfa_enrollment_required` is true — no session was minted.

refresh_tokenstring

Long-lived token that mints a new access token via `refresh`. Rotated on use.

token_typeobject

Always `Bearer`.

expires_innumber

Lifetime of the access token in seconds.

mfa_enrollment_requiredobject

Set 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_tokenstring

Enrolment 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_atstring

ISO-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"
}