Check Who the Current HTTP Session Belongs To

GET 
https://accounts.<domain>/auth/sessions/whoami

Uses the HTTP Headers in the GET request to determine (e.g. by using checking the cookies) who is authenticated. Returns a session object in the body or 401 if the credentials are invalid or no credentials were sent.

If you call this endpoint from a server-side application, you must forward the HTTP Cookie Header to this endpoint:

pseudo-code example
router.get('/protected-endpoint', async function (req, res) {
const session = await client.toSession(undefined, req.header('cookie'))

console.log(session)
})

When calling this endpoint from a non-browser application (e.g. mobile app) you must include the session token:

pseudo-code example
...
const session = await client.toSession("the-session-token")

console.log(session)

When using a token template, the token is included in the tokenized field of the session.

pseudo-code example
...
const session = await client.toSession("the-session-token", { tokenize_as: "example-jwt-template" })

console.log(session.tokenized) // The JWT

Depending on your configuration this endpoint might return a 403 status code if the session has a lower Authenticator Assurance Level (AAL) than is possible for the identity. This can happen if the identity has password + webauthn credentials (which would result in AAL2) but the session has only AAL1. If this error occurs, ask the user to sign in with the second factor or change the configuration.

This endpoint is useful for:

AJAX calls. Remember to send credentials and set up CORS correctly! Reverse proxies and API Gateways Server-side calls - use the X-Session-Token header!

Request

Query Parameters

tokenize_as string

Returns the session additionally as a token (such as a JWT)

The value of this parameter has to be a valid, configured Session token template. For more information head over to the documentation.

Header Parameters

X-Session-Token string
Set the Session Token when calling from non-browser clients. A session token has a format of MP2YWEMeM8MxjkGKpH4dqOQ4Q4DlSPaj.
Example: MP2YWEMeM8MxjkGKpH4dqOQ4Q4DlSPaj
Cookie string

Set the Cookie Header. This is especially useful when calling this endpoint from a server-side application. In that scenario you must include the HTTP Cookie Header which originally was included in the request to your server.

Responses

200

session

application/json

Schema

Schema

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.

Example (from schema)

{
  "active": true,
  "authenticated_at": "2025-04-17T12:10:30.853Z",
  "authentication_methods": [
    {
      "aal": "aal0",
      "completed_at": "2025-04-17T12:10:30.853Z",
      "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": "2025-04-17T12:10:30.853Z",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "identity": {
    "created_at": "2025-04-17T12:10:30.853Z",
    "credentials": {},
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "organization_id": "string",
    "recovery_addresses": [
      {
        "created_at": "2025-04-17T12:10:30.853Z",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "updated_at": "2025-04-17T12:10:30.853Z",
        "value": "string",
        "via": "string"
      }
    ],
    "schema_id": "string",
    "schema_url": "string",
    "state": "active",
    "state_changed_at": "2025-04-17T12:10:30.853Z",
    "updated_at": "2025-04-17T12:10:30.853Z",
    "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": "2025-04-17T12:10:30.853Z",
        "via": "email"
      }
    ]
  },
  "issued_at": "2025-04-17T12:10:30.853Z",
  "tokenized": "string"
}

401

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

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

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://accounts.<domain>/auth/sessions/whoami' \
-H 'Accept: application/json'

Request Collapse all

Base URL

https://accounts.<domain>

Parameters

tokenize_as — query

X-Session-Token — header

Cookie — header