Create 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 and generate a cryptographic key pair for the specified principal. The request has no body. A successful POST /v1/keypair returns publicKey and privateKey values in the JSON response; capture the private key immediately because it may be shown only once. Use List key pairs to retrieve public keys, or Delete a key pair to remove a pair by public key.

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

Protect the private key

The private key may be returned only once.

Transfer the private key 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/keypair?principal={{principal}}
VERB:POST
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.

Response parameters#

  • 200Response body · object

    A new key pair was generated. The private key may appear only in this response.

    {

      "publicKey": "4f3c2a1908e7d6c5b4a39281706f5e4d3c2b1a0987654321fedcba9876543210",

      "privateKey": "9a8b7c6d5e4f3021122334455667788990aabbccddeeff001122334455667788"

    }
    • publicKeystring

      Public key (hex) for the new key pair.

    • privateKeystring

      Private key material (hex). May be returned only once; store it securely.

  • 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 a key pair

Generate a new key pair for the principal (no request body; response includes public and private keys).

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

  --request POST \

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

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

  --header 'Accept: application/json'
KeypairDelete

© 2024 BigState