List principals

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 principal records, optionally filtered by the glob-style pattern query parameter. Each record contains principal, type, and name.

Start with next=0, then pass the response's next value to retrieve another page. A response value of -1 means there are no more pages.

Use Get a principal for one identifier or Create or update a principal to save a configuration. If a request returns 400, verify the cursor and pattern; for 401 or 403, check the x-api-key header and access.

GET
{{host}}/v1/principal/match?next=0&pattern={{pattern}}
VERB:GET
BASE URL:{{host}}/v1/principal/match
QUERY STRING:?next=0&pattern={{pattern}}

Query parameters#

  • nextnumber
    Required

    Pagination cursor (required): use `0` for the first page; thereafter use the value returned by the previous response as the `next` query parameter. The response body returns the cursor for the next page. A value of `-1` means there is no further page — you have the last page of data.

    example: 0
  • patternstring
    Optional

    Optional glob-style pattern to filter.

    Values

    • pattern
    • *pattern
    • pattern*
    • *pattern*
    example: *

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 pagination cursor and matching principals (id, type, name) for this page.

    • nextnumber

      Pagination cursor (required): use `0` for the first page; thereafter use the value returned by the previous response as the `next` query parameter. The response body returns the cursor for the next page. A value of `-1` means there is no further page — you have the last page of data.

      example: 0
    • principalsarray[object]

      Principals that matched the pattern on this page.

      • principals[0].principalstring

        Unique identifier of this principal.

        example: tram_client
      • principals[0].typenumber

        Principal kind: application (integration) or user.

        Values

        • 1 — application
        • 2 — user
      • principals[0].namestring

        Human-readable name for this principal.

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

List principals

List principals with optional glob pattern (paginated with `next`).

curl https://api.bigstate.dev/v1/principal/match?next=0&pattern=* \

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

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

  --header 'Accept: application/json'
DeletePolicy

© 2024 BigState