Create API key

Create an API key with optional scopes, IP allowlist and rate limit, and receive its plaintext once.

POSThttps://api.tried.com.au/api-keys

Creates a new API key for the workspace. The response is the only time the plaintext key is returned: Tried stores a SHA-256 hash for lookups and an encrypted copy for signing webhooks, so store the key as soon as you receive it.

Request#

Field	Type	Required	Description
`name`	string	No	Label for the key, 1 to 80 characters. Default `API key`.
`is_webhook_key`	boolean	No	Use this key to sign outgoing webhooks. Default `false`. Setting it clears the flag on every other key in the workspace. When no key has the flag, the oldest key signs webhooks.
`scopes`	string[]	No	Limit the key to these scopes: `agents`, `calls`, `numbers`, `kb`, `analytics`, `admin`. Leave it out or send `[]` for full access. A key that includes `admin` has full access.
`allowed_ips`	string[]	No	Accept the key only from these source IPs. Up to 50 IPv4 or IPv6 addresses, matched exactly (no CIDR ranges). Leave it out or send `[]` to allow any IP.
`rate_limit_per_minute`	integer or null	No	Requests per minute for this key, 1 to 100000. `null` or left out uses the server default (600 unless the deployment sets `RATE_LIMIT_PER_KEY`).

Scopes#

Each request path maps to exactly one scope. A key with scopes set gets 403 on any path outside them.

Scope	Covers
`kb`	Knowledge base routes.
`numbers`	Phone numbers, SIP trunks, branded caller ID, verified numbers, number bindings and concurrency settings.
`calls`	Creating, reading, stopping and deleting calls, batch calls, SMS, chats and contacts.
`analytics`	Analytics, QA, alerts, dashboards and `GET /get-concurrency`.
`agents`	Agents, Retell LLMs, conversation flows, voices, tests, Conductor and workflows.
`admin`	Everything else, including API keys, public keys, exports, assets, audit log, billing and workspace settings.

Key format#

Keys look like key_ followed by 48 hex characters. Send them as Authorization: Bearer <key>. The key's ID (api_key_id) is a different value with the same prefix and 24 hex characters.

Example request#

curl -X POST https://api.tried.com.au/api-keys \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Analytics export",
    "scopes": ["analytics"],
    "allowed_ips": ["203.0.113.10"],
    "rate_limit_per_minute": 120
  }'

const res = await fetch("https://api.tried.com.au/api-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TRIED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Analytics export",
    scopes: ["analytics"],
    allowed_ips: ["203.0.113.10"],
    rate_limit_per_minute: 120,
  }),
});
const key = await res.json(); // key.api_key is shown only once

import os, requests

res = requests.post(
    "https://api.tried.com.au/api-keys",
    headers={"Authorization": f"Bearer {os.environ['TRIED_API_KEY']}"},
    json={
        "name": "Analytics export",
        "scopes": ["analytics"],
        "allowed_ips": ["203.0.113.10"],
        "rate_limit_per_minute": 120,
    },
)
key = res.json()  # key["api_key"] is shown only once

Response#

201 Created

{
  "api_key_id": "key_0d8e4b1f7a2c96e53b0f1d84",
  "name": "Analytics export",
  "masked_key": "key_81c0********7e2a",
  "is_webhook_key": false,
  "created_timestamp": 1760313600000,
  "last_used_timestamp": null,
  "scopes": ["analytics"],
  "allowed_ips": ["203.0.113.10"],
  "rate_limit_per_minute": 120,
  "api_key": "key_81c05e2d9b4a7f3c1e6d8b0a2f5c9e7d4b1a3f6c8e0d7e2a"
}

Field	Type	Description
`api_key`	string	The plaintext key. Only present in this response.
`masked_key`	string	First 8 characters, 8 asterisks, last 4 characters. This is what list and get calls show later.

The other fields match List API keys. The create is recorded in the audit log as api_key.create.

Errors#

Status	When
`400`	A field fails validation, for example an unknown scope, more than 50 IPs, a value in `allowed_ips` that is not an IP (`IP addresses only`), or a rate limit outside 1 to 100000.
`401`	Missing or invalid API key.
`403`	The key's IP allowlist or scopes reject the request (this route needs the `admin` scope), or a dashboard member calls it (`Requires role: admin or developer`).
`429`	Rate limit exceeded. See Rate limits.

See Errors for the body format.