Manage organization API keys
Create, store, use, expire, and revoke scoped API keys for an Agent Studio organization.
Create an organization API key for an integration, store its one-time secret safely, and revoke it when it is no longer needed. API keys authenticate only routes that explicitly use Agent Studio's API-key middleware; they do not provide universal access to every API route.
Before you begin
You need an authenticated Agent Studio session and the organization ID. Only organization owners and administrators can create or delete keys; any organization member can list their metadata.
Set local placeholders for the management examples:
export AGENT_STUDIO_URL="https://studio.example.com"
export ORGANIZATION_ID="org_example"
export SESSION_COOKIE="__session=replace-with-your-session-cookie"Create and use a key
List the organization's keys before creating another one:
curl --fail-with-body \
--cookie "$SESSION_COOKIE" \
"$AGENT_STUDIO_URL/api/organizations/$ORGANIZATION_ID/api-keys"The response includes metadata such as each key's id, name, prefix, scopes, expiration, creation time, and last-use time. It does not return existing secrets.
Use the narrowest scopes required by the route you plan to call. Scope checks accept the wildcard * or the exact scope required by a wrapped handler. Omitting scopes creates a wildcard key, so provide an explicit array for least privilege.
Choose a future ISO 8601 timestamp for expiresAt. Agent Studio rejects an invalid or past timestamp. For the example, replace 2030-01-01T00:00:00.000Z with a date that matches your rotation policy.
Use a descriptive name between 2 and 100 characters:
curl --fail-with-body \
--request POST \
--cookie "$SESSION_COOKIE" \
--header "Content-Type: application/json" \
--data '{
"name": "Documentation automation",
"scopes": ["executions:create", "executions:read"],
"expiresAt": "2030-01-01T00:00:00.000Z"
}' \
"$AGENT_STUDIO_URL/api/organizations/$ORGANIZATION_ID/api-keys"Agent Studio returns HTTP 201. The data.secret field contains the only retrievable copy of the full key; the remaining fields identify the key and its policy.
Copy data.secret directly into your approved secret manager. Associate it with the returned key ID, organization, scopes, owner, and expiration date so another administrator can rotate it without exposing the value.
Do not attempt to recover the key by listing it later. Agent Studio stores a hash and prefix rather than the original secret.
For a route documented as accepting organization API keys, prefer the X-API-Key header:
curl --fail-with-body \
--header "X-API-Key: $AGENT_STUDIO_API_KEY" \
"$AGENT_STUDIO_URL/api/supported-route"The middleware also accepts Authorization: Bearer <key>. An api_key query parameter exists for webhook callbacks, but query credentials can leak through logs and browser history; use it only when a documented callback requires it.
The route receives the key's organization ID and scopes. A scope-aware handler returns HTTP 403 when the key lacks its required scope.
List the keys again and locate the key by its ID or prefix. After a successful request, lastUsedAt reflects validation of that key. Keep expiresAt in your operational inventory; an expired key fails validation with HTTP 401.
Rotate or revoke a key
API keys cannot be edited or recovered. To rotate one, create a replacement, update the consuming integration, verify the replacement, and then delete the old key:
export KEY_ID="key_to_revoke"
curl --fail-with-body \
--request DELETE \
--cookie "$SESSION_COOKIE" \
"$AGENT_STUDIO_URL/api/organizations/$ORGANIZATION_ID/api-keys/$KEY_ID"The delete route returns success: true. A later request with the revoked key returns HTTP 401.
Troubleshooting
Next steps
Review API authentication, errors, and limits before integrating the key, and use audit events to review administrative key changes.