Authentication and API keys

How to create a key, what live and test keys are, which scopes exist and how to rotate a key.

Send your key

Every request carries the key as a bearer token: Authorization: Bearer <key>. A key belongs to one organization and only sees that organization's data.

curl https://infynia.quantylcore.com/api/v1/agents \
  -H "Authorization: Bearer $INFYNIA_API_KEY"

An invalid, expired or revoked key always gets the same 401 answer with the code unauthorized.

Create a key

Open Developers, then Keys in the dashboard. Owners and admins create and revoke keys; members only see the list.
Choose a name, the scopes, an expiry (30 days, 90 days, 1 year or never) and optionally the agents the key may use.
The key is displayed once. INFYNIA keeps only a hash: lost keys cannot be recovered, create a new one.
An organization can hold up to 20 keys. Creating, rotating and revoking keys is recorded in the audit trail.

inf_live_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The format is inf_<environment>_<prefix>_<secret>. The prefix identifies the key in the dashboard and in the logs; never log the whole key.

Live and test keys

inf_live_ keys are reserved for organizations on a paid plan. Without one, creating or using a live key answers 403 with plan_required. Calls placed with a live key use the minutes of your plan.
inf_test_ keys are free for everyone and call the same routes.

With a test key, calls and campaigns are simulated: no real call, no minute deducted (see the test mode guide). Contacts remain real data.

Scopes

A key can only do what its scopes allow; a missing scope answers 403 with forbidden. Scopes follow the pattern resource:read or resource:write.

Scope	Allows	Available
`calls:write`	Place an outbound call	Yes
`calls:read`	Read a call	Yes
`agents:read`	List agents	Yes
`tasks:read`	List scheduled calls	Yes
`tasks:write`	Cancel a scheduled call	Yes
`webcalls:write`	Create a web call session token	Yes
`contacts:read`, `contacts:write`, `transcripts:read`, `campaigns:read`, `campaigns:write`, `knowledge:read`, `knowledge:write`	Reserved for resources that are not in the API yet	Not yet

A key restricted to some agents gets 403 with forbidden_agent when it touches another agent, and agent lists only show the allowed ones. An empty list means all agents.

Expiry and rotation

A reminder e-mail is sent 7 days before a key expires.
Rotating a key creates a new key with the same scopes and restrictions. The old key keeps working for 24 hours so that you can deploy the new one without downtime, then stops.
Revoking a key takes effect immediately.