List key pairs

A key pair is a public and private key associated with a principal. The private key is returned only at creation time; the public key identifies the pair for listing and deletion.

List key pairs 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. Each item contains the public key that identifies the pair; private keys are not returned. Use a returned public key with Delete a key pair, or generate another pair with Create a key pair.

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.

Keep private keys separate

This response contains public keys only.

Do not attach private keys to list requests or include them in logs while troubleshooting. Keep private key material in a secure credential store.

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

Query parameters#

  • principalstring
    Required

    Principal whose key pairs 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 key pairs 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
    • keyPairsarray[object]

      Key pairs that matched the pattern on this page.

      • keyPairs[0].publicKeystring

        Public key (hex) identifying this key pair.

  • 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 key pairs

List public keys for a principal with optional glob pattern (paginated with `next`).

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

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

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

  --header 'Accept: application/json'
DeleteDelivery

© 2024 BigState