Exchange Session Token
GET/auth/sessions/token-exchange
Exchange Session Token
Request
Query Parameters
The part of the code return when initializing the flow.
The part of the code returned by the return_to URL.
Responses
- 200
- 403
- 404
- 410
- default
successfulNativeLogin
- application/json
- Schema
- Example (from schema)
Schema
- Array [
- ]
- Array [
- ]
- Array [
- ]
- Array [
- ]
session objectrequired
A Session
Active state. If false the session is no longer active.
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.
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.
When the authentication challenge was completed.
Possible values: [link_recovery
, code_recovery
, password
, code
, totp
, oidc
, webauthn
, lookup_secret
, v0.6_legacy_session
]
The Organization id used for authentication
OIDC or SAML provider id used for authentication
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
Device record ID
IPAddress of the client
Geo Location corresponding to the IP Address
UserAgent of the client
The Session Expiry
When this session expires at.
Session ID
identity object
An identity represents a (human) user.
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
CreatedAt is a helper struct field for gobuffalo.pop.
Identifiers represents a list of unique identifiers this credential type matches.
Possible values: [password
, totp
, oidc
, webauthn
, lookup_secret
, code
]
and so on.
UpdatedAt is a helper struct field for gobuffalo.pop.
Version refers to the version of the credential. Useful when changing the config schema.
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.
NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-
NullJSONRawMessage represents a json.RawMessage that works well with JSON, SQL, and Swagger and is NULLable-
recovery_addresses object[]
RecoveryAddresses contains all the addresses that can be used to recover an identity.
CreatedAt is a helper struct field for gobuffalo.pop.
UpdatedAt is a helper struct field for gobuffalo.pop.
SchemaID is the ID of the JSON Schema to be used for validating the identity's traits.
SchemaURL is the URL of the endpoint where the identity's traits schema can be fetched from.
format: url
Possible values: [active
, inactive
]
The state can either be active
or inactive
.
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
.
UpdatedAt is a helper struct field for gobuffalo.pop.
verifiable_addresses object[]
VerifiableAddresses contains all the addresses that can be verified by the user.
When this entry was created
The ID
VerifiableAddressStatus must not exceed 16 characters as that is the limitation in the SQL Schema
When this entry was last updated
The address value
example foo@user.com
Indicates if the address has already been verified
Possible values: [email
, sms
]
The delivery method
The Session Issuance Timestamp
When this session was issued at. Usually equal or close to authenticated_at
.
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
.
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!
{
"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"
}
errorGeneric
- application/json
- Schema
- Example (from schema)
Schema
error objectrequired
The status code
Debug information
This field is often not exposed to protect against leaking sensitive information.
details object
Further error details
The error ID
Useful when trying to identify various errors in application logic.
Error message
The error's message.
A human-readable reason for the error
The request ID
The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.
The status description
{
"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"
}
}
errorGeneric
- application/json
- Schema
- Example (from schema)
Schema
error objectrequired
The status code
Debug information
This field is often not exposed to protect against leaking sensitive information.
details object
Further error details
The error ID
Useful when trying to identify various errors in application logic.
Error message
The error's message.
A human-readable reason for the error
The request ID
The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.
The status description
{
"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"
}
}
errorGeneric
- application/json
- Schema
- Example (from schema)
Schema
error objectrequired
The status code
Debug information
This field is often not exposed to protect against leaking sensitive information.
details object
Further error details
The error ID
Useful when trying to identify various errors in application logic.
Error message
The error's message.
A human-readable reason for the error
The request ID
The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.
The status description
{
"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"
}
}
errorGeneric
- application/json
- Schema
- Example (from schema)
Schema
error objectrequired
The status code
Debug information
This field is often not exposed to protect against leaking sensitive information.
details object
Further error details
The error ID
Useful when trying to identify various errors in application logic.
Error message
The error's message.
A human-readable reason for the error
The request ID
The request ID is often exposed internally in order to trace errors across service architectures. This is often a UUID.
The status description
{
"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"
}
}