Sign in

A token is a short-lived session credential issued for a principal after successful authentication. Use it in place of an API key for the duration of the session, then revoke it when it is no longer needed.

Authenticate with your API key in x-api-key and sign in as the requested principal. A successful POST /v1/token returns a session token and its expirationTime in ISO 8601 format; handle both fields from the JSON response and stop using the token when it expires. The request body may be empty. To revoke an issued token before it expires, see Revoke a token.

If the request returns 401, check that the API key is present and valid. A 403 means the key does not have sufficient rights, while a 400 indicates an invalid request such as a malformed or missing principal.

Protect issued tokens

Treat session tokens as credentials.

Keep tokens out of source control, client-side code, URLs other than the required request parameter, and application logs. Store them securely and revoke tokens that are no longer needed.

POST
{{host}}/v1/token?principal={{principal}}
VERB:POST
BASE URL:{{host}}/v1/token
QUERY STRING:?principal={{principal}}

Query parameters#

  • principalstring
    Required

    Principal identifier to sign in as (e.g. owner or logical principal id).

    example: root

Headers#

Send these headers with the request. Names are case-insensitive per HTTP rules.
  • x-api-keyRequired

    Your BigState API key.

    {{apiKey}}
  • Content-TypeRequired

    MIME type of the request body.

    application/json
  • AcceptRequired

    MIME types the client can understand in the response.

    application/json

Need a session token? See Token sign in.

Response parameters#

  • 200Response body · object

    Success. Returns a session **token** and its **expirationTime** for the principal.

    {

      "token": "9ej80prYt8pRKPdgw7AI9I1eHYPhakIf",

      "expirationTime": "2026-03-31T15:49:17.2245429+00:00"

    }
    • tokenstring

      Opaque token string; send it where required, or call `DELETE /v1/token` with this value to revoke.

    • expirationTimestring

      When the token stops being valid (ISO 8601 with offset).

  • 401

    Unauthorized.

  • 403

    Access denied. The caller does not have sufficient rights to perform this operation.

  • 400Response body · object

    Bad request.

    {

      "error": 6,

      "desc": "Invalid request"

    }
    • errornumber

      Numeric error code. Use the response `desc` field for the human-readable explanation.

    • descstring

      Human-readable description of the error.

Examples#

Sign in

Create a session token for the given principal (body optional; JSON headers).

curl https://api.bigstate.dev/v1/token?principal=root \

  --request POST \

  --header 'x-api-key: YOUR_API_KEY' \

  --header 'Content-Type: application/json' \

  --header 'Accept: application/json'
TokenRevoke

© 2024 BigState