Token sign in

Sign in as a principal using your API key: POST /v1/token?principal=… returns a session token and expirationTime (ISO 8601) for that principal. Request body is typically empty; use Content-Type: application/json and Accept: application/json like other JSON endpoints.

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.

    *provide api key here*
  • Content-TypeRequired

    MIME type of the request body.

    application/json
  • AcceptRequired

    MIME types the client can understand in the response.

    application/json

See authentication headers here.

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. See the error codes reference for the full list.

    • descstring

      Human-readable description of the error.

Examples#

Sign in with principal

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'
GetDelete

© 2024 BigState