Register an owner

An owner is the party that owns the data and every account under it: objects, principals, API keys, policies, and key pairs. Registration returns the owner id, the root API key, and the root key pair once.

The request has no body. Authenticate it with an edge signature: sign nonce + timestamp with the edge private key and send x-bs-edge-sign, x-bs-edge-sign-nonce, and x-bs-edge-sign-ts. Do not send x-api-key.

A successful response contains owner, rootApiKey, rootPublicKey, and rootPrivateKey. If the request returns 401, the edge signature is missing or invalid.

Save the root API key and private key

They are returned only in this response.

Store rootApiKey and rootPrivateKey in a credential manager before discarding the response. They are not available from a later call.

POST
{{host}}/v1/owner
VERB:POST
BASE URL:{{host}}/v1/owner

Headers#

Send these headers with the request. Names are case-insensitive per HTTP rules.
  • x-bs-edge-signRequired

    Uppercase hex Ed25519 signature of `nonce + timestamp`. Signed with the edge private key. Do not append a public key.

    SIGNATURE
  • x-bs-edge-sign-nonceRequired

    Nonce for this signature. 7–13 alphanumeric characters. Use a new nonce for each request.

    NONCE
  • x-bs-edge-sign-tsRequired

    Unix time in seconds, as a decimal string, included in the signed text.

    TIMESTAMP
  • Content-TypeRequired

    MIME type of the request body. This request has no body.

    application/json
  • AcceptRequired

    MIME types the client can understand in the response.

    application/json

Response parameters#

  • 200Response body · object

    An owner was created. The root API key and root private key are returned only in this response.

    {

      "owner": "YOUR_OWNER",

      "rootApiKey": "YOUR_API_KEY",

      "rootPublicKey": "YOUR_PUBLIC_KEY",

      "rootPrivateKey": "YOUR_PRIVATE_KEY"

    }
    • ownerstring

      Id of the owner. It identifies who holds the data, and it is written into object names as name@owner.

    • rootApiKeystring

      API key for the root principal. Store it immediately.

    • rootPublicKeystring

      Public half of the root key pair.

    • rootPrivateKeystring

      Private half of the root key pair. Store it immediately. It is used to sign requests.

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

Register an owner

Create an owner. No request body. Authenticate with an edge signature, not an API key.

curl https://api.bigstate.dev/v1/owner \

  --request POST \

  --header 'x-bs-edge-sign: SIGNATURE' \

  --header 'x-bs-edge-sign-nonce: NONCE' \

  --header 'x-bs-edge-sign-ts: TIMESTAMP' \

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

  --header 'Accept: application/json'
OwnerPrincipal

© 2024 BigState