API keys
An API key is the identity your system calls the API with: bound to one governed deployment, carrying the scopes, workflows and limits your administrator chose, and issued as two credentials shown exactly once. Read this if you hold a key: what it allows, and how it changes over its life.
Before you start: your administrator mints the key in the Organisations console under Identity & Access Management, Programmatic Access (Programmatic access); Studio has no key screen.
Steps
1. Receive the two credentials
The dialog after Create shows both values once; AlphaAgent keeps only SHA-256 hashes.
- API key, sent as
Authorization: Bearer <key>on every call. Shapeak_<key_id>.<secret>: the key id (ak_and 12 hexadecimal characters), a dot, the secret. - Key external id, sent as the
X-AlphaAgent-Key-External-Idheader on every call: the second factor. Shapeake_and 32 hexadecimal characters.
A lost value cannot be recovered; your administrator rotates the secret or issues a new external id.
2. Read the key's contract
GET /me returns everything the administrator chose (Authentication):
| The key carries | For your calls | Bounds |
|---|---|---|
| Deployment | The one governed deployment the key works against | Fixed for the life of the key |
| Workflows | Every workflow active in the deployment, now and later, or a fixed list | Up to 50 specific workflows |
| Scopes | workflows:read, runs:create (always with workflows:read), runs:read, outputs:read, optionally runs:delete; the route table says which each unlocks | At least one |
| Source IP allow-list | Classless Inter-Domain Routing (CIDR) ranges the caller's public address must fall in; empty means any address; IPv4 and IPv6 | Up to 32 ranges |
| Expiry | 30, 90 (default), 180 or 365 days from creation; every call fails once it has passed | Never more than 365 days |
| Rate limit | Requests per minute, all routes together | Default 60; at most 10,000 |
| Daily run quota | Runs started per day; resets at 00:00 Coordinated Universal Time (UTC) | Default 100; at most 100,000 |
| Concurrent runs | Runs in flight at once | Default 10; at most 100 |
| Allowed hours (UTC) | An optional daily window outside which calls are refused; an end before the start wraps midnight | Start and end differ |
3. Know how the key changes over its life
Changes reach the deployment within about a minute; a revocation within two minutes.
- Edit. Every field except the deployment. Your credentials stay the same;
GET /meshows the new contract. - Rotate. A new secret is issued; the old one keeps working for an overlap of 1 hour, 24 hours (the default), 3 days or 7 days. Switch your callers inside the overlap. The key id and the external id do not change.
- New external id. No overlap: the old value stops as soon as the deployment picks the change up; update every caller straight away. The secret does not change.
- Revoke. Final. Every call fails within two minutes and the key cannot be reactivated; your administrator creates a new key. A revoked key can then be deleted from the console, its audit trail staying behind.
- Expiry. Once the date passes every call fails, as for a revoked key.
What you should see
| Status in the console | Your calls |
|---|---|
Not yet active in <deployment> | Just created or changed; 401 or 503 for about a minute |
| Active | Accepted |
Rotating until <date> | Both the old and the new secret are accepted until then |
| Revoked · effective in the deployment within 2 minutes, then Revoked | Every call fails |
| Expired | Every call fails |
Notes
- The console refuses to bind a key to a deployment on a Studio release that does not serve the API (below 1.0.139), and names the release it needs.
- Rejected calls (wrong secret, wrong external id, address outside the allow-list) are counted; the console flags the key after rejections in the last hour and raises an alarm at 20 in an hour.
- Accepted requests roll up hourly into the administrator's Usage view; per-request detail (method, path, status, IP, reason) stays in the deployment for 90 days.
- A lost or leaked secret: ask for Rotate; the old secret stops at the end of the overlap. A lost or leaked external id: ask for New external id; the old value stops within about a minute.
Related
- Programmatic access: the console screen, for administrators.
- Authentication: how the two credentials are sent and checked.
- Limits, errors and codes: the limits as the caller sees them.