Api keys

Create an API key

Create a named, organization-scoped API key. With no `permissions` the key has full access; supply a `permissions` object to restrict it to a whitelist (only flags set `true` are granted). The raw `secret` is returned **once** in this response and never again — store it now. A restricted key that tries to mint a child with more permissions than itself is forbidden, and the per-tenant key limit is enforced.

POST
/api-keys

Create a named, organization-scoped API key. With no permissions the key has full access; supply a permissions object to restrict it to a whitelist (only flags set true are granted). The raw secret is returned once in this response and never again — store it now. A restricted key that tries to mint a child with more permissions than itself is forbidden, and the per-tenant key limit is enforced.

Authorization

x-api-key<token>

The per-tenant API key. Sent as the x-api-key request header. The key is tenant-scoped.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The body for creating an API key.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api-keys" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'
{  "api_key_id": "string",  "name": "string",  "prefix": "string",  "permissions": {    "property1": true,    "property2": true  },  "scope_type": "organization",  "scope_inbox_id": "string",  "created_at": "2019-08-24T14:15:22Z",  "last_used_at": "2019-08-24T14:15:22Z",  "secret": "string"}
{  "name": "string",  "message": "string"}
{  "name": "string",  "message": "string"}
{  "name": "validation",  "errors": {    "property1": "string",    "property2": "string"  }}
{  "name": "string",  "message": "string"}

Rate limits

Per-key request limits, the 429 response with Retry-After, and how to back off correctly.

Create an inbox-scoped API key POST

Create an API key pinned to this inbox (`scope_type=inbox`). The key can only ever operate on this one inbox. Otherwise identical to creating an organization key: the raw `secret` is returned **once**, and the no-escalation and key-limit rules apply. A key not permitted this inbox, or attempting to broaden its own scope, is forbidden.