Programmatic access
For Owners, Operators and ProgrammaticAccessAdministrators minting the API keys other systems use to run your workflows; ProgrammaticAccessViewers read the list and usage. Each key is bound to one governed deployment and shown once. The caller's side is in Programmatic access.
Before you start: you need a governed deployment (Deploy your first Studio) on Studio 1.0.139 or later (every release in the current catalogue qualifies, so the gate only bites a deployment that predates it); without one New API key is disabled, and a deployment below it is listed with "needs 1.0.139" and refused.
Read the list
Open Identity & Access Management → Programmatic Access. Columns are Name (with the key id), Deployment, Workflows ("All active" or "N workflow(s)"), Status, Expires, Last used, Requests (24 h) and the actions. Status is Active, Rotating until <date>, Not yet active in <deployment>, Revoked, Revoked · effective in the deployment within 2 minutes or Expired. Twenty rejected credential or source-address attempts within an hour add an Auth failures warning. Actions: Usage always; Edit, Rotate, New external id and Revoke on an active or rotating key; Delete on a revoked or expired one.
Create a key
Click New API key.
| Field | Values |
|---|---|
| Name, Description | Up to 100 and 500 characters. |
| Deployment | A governed deployment; fixed for the life of the key. In a standard deployment each user owns what they create, so a key-triggered run would have no owner. |
| Workflows | All active workflows, or Specific workflows ticked from the deployment's list ("<name> · v<version>"), up to 50. A freshly governed deployment's list appears within about a minute. |
| Scopes | workflows:read, runs:create, runs:read, outputs:read (ticked by default) and runs:delete (erase a run's data, right to erasure). runs:create requires workflows:read. |
| Source IP allow-list (one CIDR per line) | Empty allows any address; up to 32 ranges, IPv4 or IPv6. |
| Expiry | 30, 90 (default), 180 or 365 days. |
| Rate limit (requests per minute), Daily run quota, Concurrent runs | Defaults 60, 100 and 10; whole numbers of at least 1; at most 10,000, 100,000 and 100. |
| Only accept calls during allowed hours (UTC) | Optional From (UTC) and Until (UTC), default 08:00 to 18:00; they must differ. |
Click Create.
Copy the credentials
After Create, a rotation or a new external id, a dialog shows the two values the caller needs: the API key, sent as Authorization: Bearer <key>, and the Key external id, sent as the X-AlphaAgent-Key-External-Id header on every call as the second factor. AlphaAgent does not store them and cannot show them again; tick I have stored the key before Close.
Edit, rotate, replace the external id, revoke, delete
- Edit changes everything except the deployment; expiry offers Keep the current expiry.
- Rotate issues a new secret now; the old one keeps working for an overlap of 1 hour, 24 hours (default), 3 days or 7 days (maximum), and the key reads Rotating until <date>.
- New external id has no overlap: the current id stops working within about a minute, so update every caller straight away.
- Revoke: every call fails within two minutes; irreversible.
- Delete removes a revoked or expired key from the list and the deployment; its audit trail stays.
Read a key's usage
Usage shows Requests (24 h), Last used, Rejected auth/IP (last hour), seven days of hourly bars, and the key's Audit trail: Created, Edited, Secret rotated, Key external id rotated, Revoked, Deleted, Active in the deployment, Expired, Run data purged, each with who did it (platform actions read "AlphaAgent Organisations").
What you should see
- A new key reads Not yet active in <deployment> for up to about a minute, then Active.
- Every lifecycle action appears in the key's trail and in Audit; calls appear under the deployment's User attribution as an API-key principal (Deployment detail).
Notes
- Governed deployments only; the binding cannot change, so another deployment needs another key.
- Usage is collected from the deployment once an hour; per-request detail (method, path, status, IP, reason) stays in the deployment for 90 days and is not proxied through Organisations.
- Auth failures: investigate the caller, then rotate or revoke. A caller receiving 401 or 403 should check both headers, the allow-list and the allowed hours (Authentication).