API keys

Create an API key

The secret is returned once and never again: data.api_key.key is the only place it ever appears.

Accepts name and, optionally, scopes; any other field is a 400 rather than silently ignored. A new key is refused with a 400 (Maximum of 10 API keys allowed per account) while the account already has 10 active keys, on every plan (dashboard sign-in sessions and connected apps do not count); revoke one first. The cap is checked only here: keys suspended when a subscription ended are not counted, and resubscribing restores them, so an account can hold more than 10 that way and then cannot create another until it is under 10. GET /v1/usage/limits publishes the cap as limits.api_keys. Omitting scopes creates an unrestricted key. Sending scopes creates a key limited to exactly those scopes: an empty array is refused (a key that can do nothing is never what was meant) and so is null (omitted and null are not the same thing, and this route will not guess which was meant). A scope a key does not hold answers 403 INSUFFICIENT_SCOPE on use, naming what it needed.

Creating a key with a dashboard session needs a sign-in within the last 15 minutes; an older session answers 403 REAUTHENTICATION_REQUIRED. Creating one with an API key has no such limit, but the key used must itself be unrestricted: no scope grants minting.

post/v1/api-keys

Request

  • Base URL: https://api.kawaa.com
  • URL: https://api.kawaa.com/v1/api-keys
  • Auth: one of:
    • API key in header X-Api-Key
    • HTTP bearer

Request body

namestring required

A label for the key, for your own benefit. Measured after trimming: surrounding whitespace is trimmed before the 1-100 length check, so a 100-character name padded with spaces is accepted and stored trimmed, while a raw maxLength would refuse it, and " " satisfies a raw minLength: 1 and is refused anyway. The \S pattern stays because it is the one part that survives trimming: it requires at least one non-whitespace character.

scopesstring[]

Limit the new key to these scopes. Omit the field for an unrestricted key; [] and null are both 400s. A :write scope implies its :read half, so verification:write alone can read results. The stored list is normalized to this document's order, so the response may not list them as sent. Duplicates are accepted and collapsed into one de-duplicated list in a fixed order, so ["verification:read", "verification:read"] creates the same key as one entry. No uniqueItems here for that reason: it would refuse locally a payload the API takes. The maxItems limit applies to the RAW array, before de-duplication.

Response

The new key. Save it now.

successunknown required

Example response

{
  "data": {
    "api_key": {
      "key_id": "key_a1b2c3d4",
      "warning": "Save this API key now. You will not be able to see it again."
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.