Get your API keys
Create an API key, limit what it can do, check it, and rotate it without downtime.
An API key identifies your organization to the API. Your server sends it in the X-API-Key header on every request.
curl https://api.dialgem.com/v1/agents -H "X-API-Key: $DIALGEM_API_KEY"Store it in an environment variable or a secrets manager, not in your code.
Create a key
An owner or admin creates keys in the dashboard under Settings, API keys. If your organization requires two-step verification, you may be asked to confirm with your second step before the key is made.
When you create a key you choose:
| Setting | What it does |
|---|---|
| Name | A label for you, such as production-backend. Up to 255 characters. |
| Scopes | The actions the key may perform, for example reading agents or writing calls. Leave it out for a key that can do everything. |
| Allowed addresses | IP addresses or CIDR ranges the key may be used from. Leave it out to allow any address. |
| Expiry | A date at most three years away. Leave it out for a key that never expires. |
Give each key only what it needs. See API key scopes for the full list and how refusals look.
The key is shown once
The full key appears only when you create it, and it cannot be recovered afterwards. Dialgem keeps only a hash of it. Copy it into your secrets store straight away. If you lose it, make a new key and revoke the old one.
Check a key
GET /v1/api-key-info tells an integration what it was given: the organization, the role, and for an API key its name, first characters, scopes, expiry and last use. It works for any valid key whatever its scopes, and it never returns the key itself.
curl https://api.dialgem.com/v1/api-key-info \
-H "X-API-Key: $DIALGEM_API_KEY"Use it as a startup check, so a deployment with a wrong, expired or under-scoped key fails fast instead of on the first customer call. See the reference.
When a key is refused
| Response | Meaning |
|---|---|
401 | The key is missing, wrong, expired or revoked, or the request came from an address the key does not allow. |
403 with INSUFFICIENT_SCOPE | The key is valid but lacks the scope that call needs. Make a new key with it; scopes cannot be edited. |
Always send keys in X-API-Key. The Authorization: Bearer header is for dashboard sessions, not API keys.
Rotate a key
Rotating means replacing a key without a gap.
Create the new key
Give it the same scopes and addresses as the old one, and a name that says when it was made.
Deploy it
Put the new key in your secrets store and roll your servers over to it.
Confirm the old key is idle
The key list shows when each key was last used. When the old one stops showing recent use, nothing depends on it.
Revoke the old key
Revoking takes effect immediately and cannot be undone. Requests with that key then answer 401. Every key creation and revocation is recorded in the audit log.
If a key may have leaked, skip straight to revoking it, then create its replacement.
Keep keys on the server
Never put an API key in a browser or mobile app. For browsers, use a web call token instead.