Get a principal

A principal is an application or user identity that interacts with BigState. Principals are the subjects of authorization policies and the owners of API keys, tokens, and key pairs.

Returns the principal identified by the principal query parameter. The response contains principal, type, and name, matching each record returned by List principals.

Use Create or update a principal to create a missing record or replace its configuration. A successful lookup returns 200 OK; an unknown identifier returns 404.

If the request returns 400, verify the query parameter. For 401 or 403, check the x-api-key header and the key's access to the principal.

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

Query parameters#

  • principalstring
    Required

    Unique identifier of the principal in the URL.

    example: tram_client

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

    Current principal: **`principal`** (id), **`type`**, and **`name`** (same shape as each match row).

    {

      "principal": "tram_client",

      "type": 1,

      "name": "Client for tram app"

    }
    • principalstring

      Unique identifier of this principal.

      example: tram_client
    • typenumber

      Principal kind: application (integration) or user.

      Values

      • 1 — application
      • 2 — user
    • namestring

      Human-readable name for this principal.

  • 401

    Unauthorized.

  • 403

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

  • 404

    No principal exists for the given identifier.

  • 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#

Get a principal

Fetch `principal`, `type`, and `name` by identifier (same shape as match rows).

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

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

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

  --header 'Accept: application/json'
Create or updateDelete

© 2024 BigState