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 and is used to sign requests. The public key identifies the pair for listing, deletion, and request signatures.

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