Exchange Session Token

GET 
https://apis.<domain>/auth/sessions/token-exchange

Exchange Session Token

Request

Query Parameters

init_code stringrequired

The part of the code return when initializing the flow.

return_to_code stringrequired

The part of the code returned by the return_to URL.

Responses

200

successfulNativeLogin

application/json

Schema

Schema

session objectrequired

A Session

active boolean

Active state. If false the session is no longer active.

authenticated_at date-time

The Session Authentication Timestamp

When this session was authenticated at. If multi-factor authentication was used this is the time when the last factor was authenticated (e.g. the TOTP code challenge was completed).

authentication_methods object[]

A list of authenticators which were used to authenticate the session.

Array [

aal Authenticator Assurance Level (AAL)

Possible values: [aal0, aal1, aal2, aal3]

The authenticator assurance level can be one of "aal1", "aal2", or "aal3". A higher number means that it is harder for an attacker to compromise the account.

Generally, "aal1" implies that one authentication factor was used while AAL2 implies that two factors (e.g. password + TOTP) have been used.

completed_at date-time

When the authentication challenge was completed.

method The method used

Possible values: [link_recovery, code_recovery, password, code, totp, oidc, webauthn, lookup_secret, v0.6_legacy_session]

organization string

The Organization id used for authentication

provider string

OIDC or SAML provider id used for authentication

]

authenticator_assurance_level Authenticator Assurance Level (AAL)

Possible values: [aal0, aal1, aal2, aal3]

The authenticator assurance level can be one of "aal1", "aal2", or "aal3". A higher number means that it is harder for an attacker to compromise the account.

Generally, "aal1" implies that one authentication factor was used while AAL2 implies that two factors (e.g. password + TOTP) have been used.

devices object[]

Devices has history of all endpoints where the session was used

Array [

id uuidrequired

Device record ID

ip_address string

IPAddress of the client

location string

Geo Location corresponding to the IP Address

user_agent string

UserAgent of the client

]

expires_at date-time

The Session Expiry

When this session expires at.

id uuidrequired

Session ID

identity object

An identity represents a (human) user.

created_at date-time

CreatedAt is a helper struct field for gobuffalo.pop.

credentials object

Credentials represents all credentials that can be used for authenticating this identity.

property name* identityCredentials

Credentials represents a specific credential type

config object

created_at date-time

CreatedAt is a helper struct field for gobuffalo.pop.

identifiers string[]

Identifiers represents a list of unique identifiers this credential type matches.

type CredentialsType represents several different credential types, like password credentials, passwordless credentials,

Possible values: [password, totp, oidc, webauthn, lookup_secret, code]

and so on.

updated_at date-time

UpdatedAt is a helper struct field for gobuffalo.pop.

version int64

Version refers to the version of the credential. Useful when changing the config schema.

id uuidrequired

ID is the identity's unique identifier.

The Identity ID can not be changed and can not be chosen. This ensures future compatibility and optimization for distributed stores such as CockroachDB.

metadata_admin nullJsonRawMessagenullable

NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-

metadata_public nullJsonRawMessagenullable

NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-

organization_id uuid4nullable

recovery_addresses object[]

RecoveryAddresses contains all the addresses that can be used to recover an identity.

Array [

created_at date-time

CreatedAt is a helper struct field for gobuffalo.pop.

id uuidrequired

updated_at date-time

UpdatedAt is a helper struct field for gobuffalo.pop.

value stringrequired

via RecoveryAddressType must not exceed 16 characters as that is the limitation in the SQL Schema.required

]

schema_id stringrequired

SchemaID is the ID of the JSON Schema to be used for validating the identity's traits.

schema_url stringrequired

SchemaURL is the URL of the endpoint where the identity's traits schema can be fetched from.

format: url

state An Identity's State

Possible values: [active, inactive]

The state can either be active or inactive.

state_changed_at date-time

traits identityTraitsrequired

Traits represent an identity's traits. The identity is able to create, modify, and delete traits in a self-service manner. The input will always be validated against the JSON Schema defined in schema_url.

updated_at date-time

UpdatedAt is a helper struct field for gobuffalo.pop.

verifiable_addresses object[]

VerifiableAddresses contains all the addresses that can be verified by the user.

Array [

created_at date-time

When this entry was created

id uuid

The ID

status identityVerifiableAddressStatusrequired

VerifiableAddressStatus must not exceed 16 characters as that is the limitation in the SQL Schema

updated_at date-time

When this entry was last updated

value stringrequired

The address value

example foo@user.com

verified booleanrequired

Indicates if the address has already been verified

verified_at date-time

via stringrequired

Possible values: [email, sms]

The delivery method

]

issued_at date-time

The Session Issuance Timestamp

When this session was issued at. Usually equal or close to authenticated_at.

tokenized string

Tokenized is the tokenized (e.g. JWT) version of the session.

It is only set when the tokenize query parameter was set to a valid tokenize template during calls to /session/whoami.

session_token string

The Session Token

A session token is equivalent to a session cookie, but it can be sent in the HTTP Authorization Header:

Authorization: bearer ${session-token}

The session token is only issued for API flows, not for Browser flows!

Example (from schema)

{
  "session": {
    "active": true,
    "authenticated_at": "2024-03-30T07:38:31.808Z",
    "authentication_methods": [
      {
        "aal": "aal0",
        "completed_at": "2024-03-30T07:38:31.808Z",
        "method": "link_recovery",
        "organization": "string",
        "provider": "string"
      }
    ],
    "authenticator_assurance_level": "aal0",
    "devices": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "ip_address": "string",
        "location": "string",
        "user_agent": "string"
      }
    ],
    "expires_at": "2024-03-30T07:38:31.808Z",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "identity": {
      "created_at": "2024-03-30T07:38:31.808Z",
      "credentials": {},
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "organization_id": "string",
      "recovery_addresses": [
        {
          "created_at": "2024-03-30T07:38:31.808Z",
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "updated_at": "2024-03-30T07:38:31.808Z",
          "value": "string",
          "via": "string"
        }
      ],
      "schema_id": "string",
      "schema_url": "string",
      "state": "active",
      "state_changed_at": "2024-03-30T07:38:31.808Z",
      "updated_at": "2024-03-30T07:38:31.808Z",
      "verifiable_addresses": [
        {
          "created_at": "2014-01-01T23:28:56.782Z",
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "status": "string",
          "updated_at": "2014-01-01T23:28:56.782Z",
          "value": "string",
          "verified": true,
          "verified_at": "2024-03-30T07:38:31.808Z",
          "via": "email"
        }
      ]
    },
    "issued_at": "2024-03-30T07:38:31.808Z",
    "tokenized": "string"
  },
  "session_token": "string"
}

403

errorGeneric

application/json

Schema

Schema

error objectrequired

code int64

The status code

debug string

Debug information

This field is often not exposed to protect against leaking sensitive information.

details object

Further error details

id string

The error ID

Useful when trying to identify various errors in application logic.

message stringrequired

Error message

The error's message.

reason string

A human-readable reason for the error

request string

The request ID

The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.

status string

The status description

Example (from schema)

{
  "error": {
    "code": 404,
    "debug": "SQL field \"foo\" is not a bool.",
    "details": {},
    "id": "string",
    "message": "The resource could not be found",
    "reason": "User with ID 1234 does not exist.",
    "request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
    "status": "Not Found"
  }
}

404

errorGeneric

application/json

Schema

Schema

error objectrequired

code int64

The status code

debug string

Debug information

This field is often not exposed to protect against leaking sensitive information.

details object

Further error details

id string

The error ID

Useful when trying to identify various errors in application logic.

message stringrequired

Error message

The error's message.

reason string

A human-readable reason for the error

request string

The request ID

The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.

status string

The status description

Example (from schema)

{
  "error": {
    "code": 404,
    "debug": "SQL field \"foo\" is not a bool.",
    "details": {},
    "id": "string",
    "message": "The resource could not be found",
    "reason": "User with ID 1234 does not exist.",
    "request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
    "status": "Not Found"
  }
}

410

errorGeneric

application/json

Schema

Schema

error objectrequired

code int64

The status code

debug string

Debug information

This field is often not exposed to protect against leaking sensitive information.

details object

Further error details

id string

The error ID

Useful when trying to identify various errors in application logic.

message stringrequired

Error message

The error's message.

reason string

A human-readable reason for the error

request string

The request ID

The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.

status string

The status description

Example (from schema)

{
  "error": {
    "code": 404,
    "debug": "SQL field \"foo\" is not a bool.",
    "details": {},
    "id": "string",
    "message": "The resource could not be found",
    "reason": "User with ID 1234 does not exist.",
    "request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
    "status": "Not Found"
  }
}

default

errorGeneric

application/json

Schema

Schema

error objectrequired

code int64

The status code

debug string

Debug information

This field is often not exposed to protect against leaking sensitive information.

details object

Further error details

id string

The error ID

Useful when trying to identify various errors in application logic.

message stringrequired

Error message

The error's message.

reason string

A human-readable reason for the error

request string

The request ID

The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.

status string

The status description

Example (from schema)

{
  "error": {
    "code": 404,
    "debug": "SQL field \"foo\" is not a bool.",
    "details": {},
    "id": "string",
    "message": "The resource could not be found",
    "reason": "User with ID 1234 does not exist.",
    "request": "d7ef54b1-ec15-46e6-bccb-524b82c035e6",
    "status": "Not Found"
  }
}

• curl
• python
• go
• nodejs
• ruby
• csharp
• php
• java
• powershell

• CURL

curl -L -X GET 'https://apis.<domain>/auth/sessions/token-exchange' \
-H 'Accept: application/json'

Request Collapse all

Base URL

https://apis.<domain>

Parameters

init_code — queryrequired

return_to_code — queryrequired