API key scopes

Limit an API key to the parts of the API it needs, the addresses it may be used from, and a date it stops working.

A new key can be limited in three ways, all optional. Set them when you create the key in Settings, API Keys.

Scopes

A scope is resource:read or resource:write. Write includes read.

Resource	Covers
`agents`	agents, folders, versions, functions, knowledge, voices, templates, flows, LLMs
`calls`	creating, reading and ending calls, sessions
`chats`	chats
`phone_numbers`	phone numbers
`contacts`	contacts, lists, imports, do-not-call
`campaigns`	campaigns
`webhooks`	webhook endpoints and deliveries
`analytics`	analytics and usage
`simulations`	agent test suites and runs
`web_calls`	browser-call settings

The key form lists them. A key without scopes is full access; the dashboard says so next to it. A limited key is refused with 403 INSUFFICIENT_SCOPE, naming the scope it needed.

A limited key can never manage the organization itself: members, invitations, API keys, billing, SIP trunks, retention or the audit log. Those routes need a signed-in owner or admin, and a route added to Dialgem later is closed to limited keys until it is deliberately opened.

Addresses

allowed_ips takes IP addresses or CIDR ranges (203.0.113.7, 10.0.0.0/8). A request from anywhere else is refused with 401. Leave it out to allow any address. 0.0.0.0/0 is rejected: it would mean "anywhere", so leave the field out instead.

Dialgem believes the X-Forwarded-For header only for the proxies it runs itself. A header you send yourself cannot widen a key's allowlist.

Expiry

expires_at is a time at most three years ahead. After it the key is refused with 401 API key expired; it stays listed so you can see that it lapsed, and you can revoke it as usual. There is no way to extend a key: create a new one.

Keys that already exist

Keys created before scopes existed keep working unchanged and are shown as Full access. To tighten one, create a limited key, switch your integration to it, then revoke the old one.