Delete 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 API key in x-api-key, then delete the API key identified by name for the specified principal. A successful DELETE /v1/apikey returns 204 No Content, so do not attempt to parse a response body. Use List API keys to confirm the key name, or Create an API key to issue a replacement.

A 404 means no key with that name exists under the principal. For 401, 403, or 400, verify the authenticating key, caller permissions, principal, and JSON request body.

Plan credential rotation

Deleted API keys can no longer authenticate requests.

Update dependent services to use a replacement credential before deleting an API key. Keep both the old and replacement secrets out of logs and source control.

DELETE
{{host}}/v1/apikey?principal={{principal}}
VERB:DELETE
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#

  • Delete by name
    {

      "name": "name1"

    }

Response parameters#

  • 204Response body · no content

    The API key was deleted.

  • 401

    Unauthorized.

  • 403

    Access denied. The caller does not have sufficient rights to perform this operation.

  • 404

    No API key exists for the given name under this principal.

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

Delete an API key

Delete an API key by name for the given principal. Success: 204, no body.

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

  --request DELETE \

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

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

  --header 'Accept: application/json' \

  --data '{

  "name": "name1"

}'
CreateList

© 2024 BigState