API · API keys

Create API key

Create an API key (requires full access).

POST/api-keysFull access

Request parameters

Parameter	Type	Description
`Idempotency-Key` header · optional	`string` 1–256 characters	Makes the request safe to retry. See Idempotency.
`name` body · required	`string` 1–50 characters	The API key name.
`permission` body · optional	`"full_access" \| "sending_access" \| null`	Key permission, defaulting to full_access for all resources; sending_access only permits sending email.
`domain_id` body · optional	`string \| null`	Sending domain restriction for a sending_access key; ignored for full_access keys.

Request example

Set OPENSEND_BASE_URL=https://api.example.com and OPENSEND_API_KEY=os_replace_me on your server.

bash

curl -X POST "$OPENSEND_BASE_URL/api-keys" \
  -H "Authorization: Bearer $OPENSEND_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Production","permission":"sending_access"}'

Response

201 · application/json. Example IDs stand for IDs returned by your installation.

json

{
  "id": "YOUR_ID",
  "token": "example"
}

Behavior and errors

Save the returned token securely: it is returned once and only its SHA-256 hash is stored. permission defaults to full_access. domain_id restricts a sending_access key to one of your team’s domains and is ignored for full-access keys; an unknown domain returns 422. The SDK takes this option as domain_id. A sending-only caller cannot create keys. The response status is 201.

Use a full-access credential. Resource IDs belong to your team; an unknown or foreign resource returns 404. See authentication, errors, rate limits, and compatibility for the shared contract.