Questions · Updated 2026-09-28

What does restricted_api_key mean?

restricted_api_key means the key on the request has permission sending_access and the endpoint is a management endpoint, which takes full_access. Create a full_access key with POST /api-keys, or keep the sending key for what it may call, which is POST /emails, POST /emails/batch, POST /emails/preflight and GET /emails for what it sent.

restricted_api_key means the API key on the request has permission sending_access, and the endpoint is a management endpoint that takes full_access. The key is valid and the request is well formed; the key is the wrong kind for this route, so retryable is false. The error catalogue message, "This API key is restricted to sending only.", says as much, and the fix names the resolving call, POST /api-keys with permission=full_access. A sending key keeps working for POST /emails, POST /emails/batch, POST /emails/preflight, and for reading what it sent.

The rule the API applies

Every key is created with one of two permissions, full_access or sending_access, and GET /api-keys returns permission per key, never the token. Management endpoints check the permission before anything else: keys (POST /api-keys, GET /api-keys), limits (GET /limits/keys/{id}, PATCH /limits/keys/{id}, POST /limits/kill-all), the approval queue (GET /agent-actions), webhooks (POST /webhooks), domains (POST /domains), suppressions (GET /suppressions), templates (GET /templates), usage and billing (GET /usage, GET /billing/plan) and the audit log (GET /audit-log). A sending_access key on any of them is answered this code. The email routes check scopes instead of permission, so a sending key sends with POST /emails, POST /emails/batch and POST /emails/preflight, cancels with POST /emails/{id}/cancel, and reads its own history with GET /emails, GET /emails/{id}, GET /emails/{id}/events and GET /emails/{id}/explain. GET /trust/standing takes any key. The Agents guide states the intent: a key with sending_access "cannot rotate keys, cannot change budgets, and cannot lift its own ceiling".

The same code answers a key whose scopes leave out the one a route needs. The message then names the scope, in the form "This endpoint requires the '…' scope.", and details lists required and available.

Which key to hand an agent

The catalogue fix says "Use a full_access key (POST /api-keys with permission=full_access) for management endpoints." The Agents guide says to give the agent its own key with its own budget rather than the key your backend uses. Read together: the agent sends on a sending_access key, and the management call that met this error is made by a person, or by a full_access key that the agent does not hold. The longer answer is which API key permission an AI agent should have.

curl -sS -X POST https://api.agentisend.com/api-keys \
  -H "Authorization: Bearer $AGENTISEND_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"yourdomain.com","permission":"sending_access"}'
201
{
  "budget_per_period": 1,
  "created_at": "2026-09-04T09:14:00Z",
  "domain_scope": "string",
  "expires_at": "2026-09-04T09:14:00Z",
  "id": "9c8f8f0e-3d1a-4d3f-9a1e-2b7c1a0f5e42",
  "last_used_at": "2026-09-04T09:14:00Z",
  "name": "yourdomain.com",
  "period": "hourly"
}
Response

The generated example creates a sending_access key, the kind that meets this error; for management calls set permission to full_access. The token is returned once. scopes and domain_scope narrow a key further, and a key sending outside its domain_scope is answered domain_scope_violation, a different code.

What not to do

retryable is false, so do not retry with the same key; nothing about the request changes the answer. Do not upgrade an agent's key to full_access so a refused call passes. A full_access key on a management endpoint can rotate keys, change limits and delete suppressions, and three things stay refused even then: approving a held send, resuming a paused key and raising a budget answer human_action_required, whose fix says "Scoping the key differently does not change the answer, and retrying fails the same way." Those are a person's, whatever the key.

Next