Create or update 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.

Creates or replaces the principal identified by the principal query parameter. The request body sets type (1 for an application or 2 for a user) and the display name.

A successful request returns 204 No Content. Use Get a principal to inspect the saved record or List principals to find principal identifiers.

If the request returns 400, verify the identifier and required body fields. For 401 or 403, check the x-api-key header and whether that key can manage principals.

POST
{{host}}/v1/principal?principal={{principal}}
VERB:POST
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.

Request body#

  • Application principal (type 1)
    {

      "type": 1,

      "name": "Client for tram app"

    }

Request parameters#

  • typenumber
    Required

    Principal kind: application (integration) or user.

    Values

    • 1 — application
    • 2 — user
  • namestring
    Required

    Human-readable name for this principal.

Response parameters#

  • 204Response body · no content

    Principal was created or updated. No response body.

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

Create or update a principal

Create or replace a principal (type 1 = application, 2 = user). Success: 204, no body.

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

  --request POST \

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

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

  --header 'Accept: application/json' \

  --data '{

  "type": 1,

  "name": "Client for tram app"

}'
PrincipalGet

© 2024 BigState