API credentials bind a service agent to the public machine API. These session-only endpoints let operators inspect metadata, choose scopes, rotate a key, or revoke it; the usable secret is returned only when a credential is created or rotated.
A key belongs to one agent
A credential inherits workspace and service-agent identity; it is not an operator login. Public routes then enforce its explicit scopes, such as traces:write or gateway:check. Later list and detail reads expose the prefix and lifecycle fields, never the original secret.
Rotation is a handoff
Rotation returns a replacement secret once, links it to the previous credential, and revokes the old credential in the same transaction. Plan the cutover, store the new value immediately, and deploy it without expecting an overlap window.
Before you begin
A signed-in browser session with a selected workspace backed by an active membership is required; an archived workspace remains readable but rejects mutations. Every /api/v1/operator endpoint rejects API credentials and bearer tokens, regardless of their scopes.
Use an owner or admin membership for create, update, rotate, and revoke operations. Any role on an active membership can read credential metadata.
Create the service agent first and decide which public API scopes its runtime actually needs.
How it works
Inventory before changing
List a service agent's credentials and compare name, scopes, expiry, last_used_at, and revoked_at. Revoked credentials are omitted from the normal list, so use the known credential detail when investigating historical metadata.
Apply least privilege
Create or rotate from /app/agents/credentials, capture the one-time secret in an approved secret store, and validate the intended public endpoint. Revoke unused keys after the new deployment is healthy.
Examples
These examples are illustrative. Replace the sample values with your own.
Keep credentials in environment variables or a secret manager, never in client-side code.
Inspect an agent's active credentials
This same-origin snippet selects the first visible service agent, then reads its credential metadata. It never prints a usable secret.
javascript
const agentsResponse = await fetch("/api/v1/operator/service_agents", {
credentials: "same-origin",
headers: {"Accept": "application/json"}
});
const agentsBody = await agentsResponse.json();
if (!agentsResponse.ok) throw new Error(`${agentsResponse.status}: ${agentsBody.detail}`);
const serviceAgent = agentsBody.service_agents[0];
if (!serviceAgent) throw new Error("Create a service agent before listing credentials");
const response = await fetch(`/api/v1/operator/service_agents/${encodeURIComponent(serviceAgent.id)}/credentials`, {
credentials: "same-origin",
headers: {"Accept": "application/json"}
});
const body = await response.json();
if (!response.ok) throw new Error(`${response.status}: ${body.detail}`);
console.log(body);
What to expect
200 OK. The response wrapper is {"api_credentials": []} when the selected agent has no active credentials; populated items include prefix and scopes but no secret.
Troubleshooting
A scoped machine key still gets 401
That is intentional: operator routes authenticate only the browser session. Sign in and select a workspace through an active membership instead of adding Authorization or x-agent-api-key headers.
An agent or credential is 404
IDs are resolved inside the current workspace. Check the workspace switcher and the UUID; an object from another workspace is deliberately indistinguishable from a missing object.
Endpoint reference
Ready to integrate? Open an endpoint for its required permissions, request fields,
response format, and status codes. The examples above explain the workflow;
these details define each individual request.
GET
/api/v1/operator/service_agents/:service_agent_id/credentials
Web Session
List service agent credentials
Description
Returns the service agent's live (unrevoked, unarchived) API credentials, newest first. Revoked and archived credentials are omitted; GET /api/v1/operator/service_agents/:id includes the full credential history.
