List API keys

An API key is a secret credential that authenticates requests for a principal. Create scoped keys for each application or environment, treat them as secrets, and delete keys that are no longer required.

List API key names for a principal, optionally filtered by a glob-style pattern. Start with next=0, then pass the next value from each JSON response to retrieve the following page; next=-1 means there are no more pages. The response contains key names, not API key secret values. Use a returned name with Delete an API key, or issue another credential with Create an API key.

If results are missing, confirm the principal and pattern and continue pagination until next=-1. A 401 indicates an authentication problem, 403 indicates insufficient rights, and 400 indicates invalid query parameters.

Protect the authenticating API key

Listing names does not reveal key secrets.

Send the API key only in x-api-key, store it securely, and never print or log it while inspecting list responses.

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

Query parameters#

  • principalstring
    Required

    Principal whose API keys are listed.

    example: root
  • 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 the matching API key names 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
    • apiKeysarray[object]

      API key names that matched the pattern.

      • apiKeys[0].namestring

        Descriptive name used to identify this apiKey configuration.

  • 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 API keys

List API keys for a principal, optionally filtered by a glob pattern (paginated).

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

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

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

  --header 'Accept: application/json'
DeleteKeypair

© 2024 BigState