Create an API key

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.

Authenticate with an existing API key in x-api-key, then create a named API key for the specified principal. A successful POST /v1/apikey returns the new apiKey secret in the JSON response; capture it immediately because it may be shown only once. Use List API keys to retrieve key names, or Delete an API key to remove a key by name.

If the request returns 401, verify the existing API key. A 403 means it lacks sufficient rights, while a 400 indicates an invalid principal or request body.

Store the new secret immediately

The API key may be returned only once.

Transfer the secret directly to a secure credential store. Never print it, log it, commit it to source control, or expose it in client-side code.

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

Query parameters#

  • principalstring
    Required

    Principal whose API keys are managed (e.g. owner or logical principal id).

    example: root

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#

  • Create named key
    {

      "name": "name1"

    }

Response parameters#

  • 200Response body · object

    API key was created. The response may include the secret value only in this response.

    {

      "apiKey": "{{apiKey}}"

    }
    • apiKeystring

      Secret API key string. May be returned only once when the key is created.

  • 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 an API key

Create a new API key for the given principal.

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

  --request POST \

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

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

  --header 'Accept: application/json' \

  --data '{

  "name": "name1"

}'
API keysDelete

© 2024 BigState