API keys

Create and revoke the keys that sign your requests. How to send a key with a request: Authentication. Test keys aren’t managed here: see Test keys.

#Rotating a key

The dashboard lists your keys in Settings → Developers → API keys, leaving out the key made when you connect an AI app (named MCP Connection). Create key, or New key on a live key’s row, makes another key; the old one keeps working until you revoke it. On a test key the button is Replace, and it does replace the key. Each key has its own Revoke. A key made for an AI app isn’t in this list: revoke the app under Connected apps on the same page. Switch everything to the new key, then revoke the old one.
Over the API, POST /v1/api-keys adds a key and the keys you already have keep working until you delete them. The dashboard shows a key you added this way too, as the newest key or as an older one: list your keys to see them all.

#The API key object

idinteger: The key’s id. Use it to delete the key.
namestring: Your label for the key.
key_prefixstring: The key’s first characters.
last4string: The key’s last four characters. Not in the create response.
kindstring: mcp for a key made when you connected an AI app, otherwise live. Not in the create response.
created_atstring: When the key was made, ISO 8601.
last_used_atstring | null: When the key was last used. null until it’s used, and it can be up to 60 minutes behind.
keystring: The full key, starting rsms_. Only in the create response; it can’t be shown again.

#List API keys

The account’s live keys, newest first, without their secrets. Revoked keys and the test key aren’t listed. With X-Sub-Account-Id it lists the sub-account’s keys.

Returns a list of API key objects in data.

curl "https://api.tryready.com/v1/api-keys" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/api-keys', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/api-keys",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": [
    {
      "id": 3307,
      "name": "Client A website",
      "key_prefix": "rsms_4f0c2a9...",
      "created_at": "2026-10-01T20:32:03.473Z",
      "last_used_at": "2026-10-28T14:05:11.902Z",
      "last4": "9b1e",
      "kind": "live"
    }
  ]
}

#Create an API key

Makes a new live key. Your other keys keep working until you delete them. The full key is in this response only: store it now. Needs the account owner’s or an admin’s key. With X-Sub-Account-Id the key belongs to that sub-account and can only ever act as it, so give each sub-account its own key this way.

Parameters

namestringDefault API Key: A label to tell your keys apart.

Returns an API key object in data, with the full key.

Errors

HTTP	Code	When
400	`invalid_request`	`name` isn’t text, or is longer than 100 characters.
500	no code	The key wasn’t made. Nothing to clean up; retry.
503	no code	The key may have been made but couldn’t be confirmed. List your keys before you retry.

curl -X POST "https://api.tryready.com/v1/api-keys" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client A website"
  }'

const res = await fetch('https://api.tryready.com/v1/api-keys', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Client A website"
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/v1/api-keys",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "name": "Client A website"
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": {
    "id": 3307,
    "name": "Client A website",
    "key_prefix": "rsms_4f0c2a9...",
    "created_at": "2026-10-01T20:32:03.473Z",
    "key": "rsms_4f0c2a97d81e5b6c03a4f9e2d7c19b1e"
  }
}

#Delete an API key

Turns a key off. It stops working on the next request. Needs the account owner’s or an admin’s key.

Parameters

idinteger · pathRequired: The key’s id from List API keys. With X-Sub-Account-Id, one of the sub-account’s keys.

Returns { "success": true }.

Errors

HTTP	Code	When
400	`invalid_request`	`id` isn’t a whole number.
404	`api_key_not_found`	No live key with that id on this account, or it was already deleted.
503	`api_key_revoke_failed`	Couldn’t confirm the key is off. List your keys, then retry.

curl -X DELETE "https://api.tryready.com/v1/api-keys/3307" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/api-keys/3307', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.delete(
    "https://api.tryready.com/v1/api-keys/3307",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true
}

#List keys across sub-accounts

Every live and test key of your main account and each of its sub-accounts, without their secrets. Needs the account owner’s key or an admin’s key on the main account. To make or delete a sub-account’s key, call Create or Delete with X-Sub-Account-Id.

Returns a list of API key objects in data, each with three more fields:

sub_account_idinteger: The account the key belongs to.
sub_account_namestring | null: That account’s name.
mainboolean: true for a key of the main account.

kind is live, test or mcp here.

Errors

HTTP	Code	When
403	`sub_account_scope_forbidden`, `organization_only`	The key’s user isn’t the owner or an admin of the main account, or can’t see sub-accounts.
422	`too_many_sub_accounts`, `too_many_api_keys`	Too many sub-accounts or keys for one list. Call List API keys with `X-Sub-Account-Id` for each sub-account instead.
503	`api_keys_unavailable`	The keys couldn’t be read. Retry.

curl "https://api.tryready.com/v1/api-keys/all" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/api-keys/all', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/api-keys/all",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": [
    {
      "id": 3307,
      "name": "Client A website",
      "key_prefix": "rsms_4f0c2a9...",
      "created_at": "2026-10-01T20:32:03.473Z",
      "last_used_at": "2026-10-28T14:05:11.902Z",
      "last4": "9b1e",
      "kind": "live",
      "sub_account_id": 4812,
      "sub_account_name": "Bright Smile Dental",
      "main": false
    }
  ]
}

#List failed requests

The requests made with your keys that got an error back (any 4xx or 5xx but 401), newest first, for the last 90 days. The same error on the same path is listed once a minute, so a retry loop shows as one row a minute, not one per request. Revoked keys’ requests are included. Phone numbers, emails and tokens are taken out of the error text, and the text is cut at 300 characters. Requests refused before we read your key (429 RATE_LIMITED, 503 ADMISSION_SHED, 413, INVALID_JSON) are not listed here; read the status and Retry-After on the response.

Parameters

qstring · query: Text to look for in the method, path, status, error code, error or request id. Up to 100 characters.
key_idinteger · query: Only this key’s requests. A key that isn’t yours gives an empty list.
beforeinteger · query: For the next page: the last id you got.
limitinteger · queryDefault 50Max 200: Page size.

Returns

data[]object[]: id, created_at, method, path, status, error_code, error, response (the error sentence and code you got, as success, error, error_code and code; other fields of the original body are not kept), request_id, key (id, name, prefix, last4, revoked), account_id and account_name.
has_moreboolean: Whether there is another page.

Errors

HTTP	Code	When
400	`invalid_request`	`key_id`, `before` or `limit` isn’t a whole number above 0.
503	`api_failures_unavailable`	The list couldn’t be read. Retry.

curl "https://api.tryready.com/v1/api-keys/failures?limit=20" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/v1/api-keys/failures?limit=20', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/v1/api-keys/failures?limit=20",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "has_more": false,
  "data": [
    {
      "id": 90211,
      "created_at": "2026-11-02T15:41:07.118Z",
      "method": "POST",
      "path": "/v1/messages",
      "status": 400,
      "error_code": "invalid_phone",
      "error": "That isn't a valid phone number: [phone]",
      "response": { "success": false, "error": "That isn't a valid phone number: [phone]", "error_code": "invalid_phone", "code": "invalid_phone" },
      "request_id": "req_7f3a91c2",
      "key": { "id": 3307, "name": "Client A website", "prefix": "rsms_4f0c2a9...", "last4": "9b1e", "revoked": false },
      "account_id": 4812,
      "account_name": "Bright Smile Dental"
    }
  ]
}