Delete a key pair

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.

Authenticate with an API key in x-api-key, then delete the key pair identified by its public key for the specified principal. Send publicKey in the JSON request body. A successful DELETE /v1/keypair returns 204 No Content, so do not attempt to parse a response body. Use List key pairs to find the public key, or Create a key pair to generate a replacement.

A 404 means the public key was not found under that principal. For 401, 403, or 400, verify the authenticating API key, caller permissions, principal, and JSON request body.

Confirm dependent systems first

Deleting a key pair removes the identified credential.

Confirm that no dependent system still needs the key pair before deleting it. Never include the corresponding private key in this request, logs, or troubleshooting output.

DELETE
{{host}}/v1/keypair?principal={{principal}}
VERB:DELETE
BASE URL:{{host}}/v1/keypair
QUERY STRING:?principal={{principal}}

Query parameters#

  • principalstring
    Required

    Principal whose cryptographic key pairs are managed.

    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 public key
    {

      "publicKey": "{{keypair}}"

    }

Request parameters#

  • publicKeystring
    Required

    Public key (hex) identifying the key pair to remove.

Response parameters#

  • 204Response body · no content

    The key pair was deleted.

  • 401

    Unauthorized.

  • 403

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

  • 404

    No key pair exists for the given public key 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 a key pair

Remove a key pair by public key for the given principal. Success: 204, no body.

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

  --request DELETE \

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

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

  --header 'Accept: application/json' \

  --data '{

  "publicKey": "{{keypair}}"

}'
CreateList

© 2024 BigState