Authentication

Overview

Authentication tells Robots Center which agent is calling and what it is allowed to do. Each service agent belongs to a workspace and uses an agk_ API key for HTTP requests. You can optionally exchange that key for a 30-day access token; realtime connections use a separate 10-minute socket token.

Four credentials, four jobs

An agk_ key and its optional 30-day access token authenticate the ordinary machine API. An enrollment token only bootstraps an identity and cannot call protected routes. A short-lived socket_token is a Phoenix connection parameter: redact WebSocket upgrade URLs and logs that expose it. Never place long-lived secrets in URLs. Operator /api/v1/operator routes instead require a signed-in browser session and do not accept these machine credentials.

Direct key use versus exchange

Protected routes accept Authorization: Bearer $AGENT_API_KEY or x-agent-api-key; exchange is optional. POST /api/v1/agent_tokens is different: it accepts the API key in x-agent-api-key or JSON api_key, and deliberately rejects an Authorization bearer value with 400.

Workspace and scope gates

Authentication pins every request to the credential's workspace and service agent. Missing scopes return 403 with extra.required_scopes; frozen, paused, or archived workspaces return 403 with a top-level error naming that workspace state.

How it works

1. Obtain and secure the primary credential

   For an existing workspace, have an owner/admin create or rotate the appropriate workspace/service-agent key or mint an enrollment token to claim once. Use registration only for a new account, and keep the returned key out of source control and browser URLs.

2. Prove the identity with a scoped read

   Call a small endpoint such as GET /api/v1/agents/me with the agk_ key. A successful response identifies the service agent; 401 means the credential is invalid or expired, while 403 usually identifies a scope or workspace-state problem.

3. Mint narrower transport credentials when useful

   Exchange the API key for a selected scope subset when a 30-day bearer token fits deployment policy. For realtime, use a REST credential carrying sockets:connect to mint the 600-second socket token immediately before opening /socket.

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.

export AGENTOPS_BASE_URL="https://robotscenter.net"
export AGENT_API_KEY="agk_value_from_your_secret_manager"

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  "$AGENTOPS_BASE_URL/api/v1/agents/me" | jq .

export AGENTOPS_BASE_URL="https://robotscenter.net"
: "${REGISTRATION_EMAIL:?Set REGISTRATION_EMAIL to a new account email you control}"
: "${REGISTRATION_PASSWORD:?Set REGISTRATION_PASSWORD to a unique 12-72 character secret}"

REGISTRATION_RESPONSE=$(jq -n \
  --arg email "$REGISTRATION_EMAIL" \
  --arg password "$REGISTRATION_PASSWORD" \
  '{email: $email, password: $password, workspace_name: "Example Robotics", agent_name: "Coordinator"}' |
  curl --fail-with-body --silent --show-error \
    -H 'content-type: application/json' \
    --data-binary @- \
    "$AGENTOPS_BASE_URL/api/v1/register")

export AGENT_API_KEY=$(printf '%s' "$REGISTRATION_RESPONSE" | jq -r '.api_key.key')
curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  "$AGENTOPS_BASE_URL/api/v1/agents/me" | jq .

export AGENTOPS_BASE_URL="https://robotscenter.net"
export AGENT_API_KEY="agk_value_from_your_secret_manager"

TOKEN_RESPONSE=$(curl --fail-with-body --silent --show-error \
  -X POST \
  -H 'content-type: application/json' \
  -H "x-agent-api-key: $AGENT_API_KEY" \
  --data '{"scopes":["agents:read","sockets:connect"]}' \
  "$AGENTOPS_BASE_URL/api/v1/agent_tokens")

export AGENT_ACCESS_TOKEN=$(printf '%s' "$TOKEN_RESPONSE" | jq -r '.token')
printf '%s' "$TOKEN_RESPONSE" | jq '{credential_id, service_agent_id, scopes, expires_in}'

export AGENTOPS_BASE_URL="https://robotscenter.net"
export AGENT_ACCESS_TOKEN="access_token_from_exchange"

curl --fail-with-body --silent --show-error \
  -X POST \
  -H "Authorization: Bearer $AGENT_ACCESS_TOKEN" \
  "$AGENTOPS_BASE_URL/api/v1/socket_tokens" | jq .

Troubleshooting

The exchange returns 400

Do not put the key in Authorization on /agent_tokens. Send the literal agk_ value as x-agent-api-key or JSON api_key; underscore variants of the header are not read.

A known key returns 401

Check for an expired, revoked, or archived credential and an inactive service agent. The exchange endpoint exposes stable details such as api_key_expired and api_key_revoked; ordinary protected routes intentionally use a less specific invalid-token response.

A valid credential returns 403

Compare extra.required_scopes with the credential's scopes, then inspect the top-level error for workspace_frozen, workspace_paused, or workspace_archived. Exchanging the key cannot bypass either gate.

The socket disconnects or rejects the token

Mint a fresh socket token, pass it as socket_token rather than as an API key, use the configured HTTPS origin in production, and keep each WebSocket frame at or below 64 KB.

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.

{
  "token": "SFMyNTY.g2gDdAAAAARtAAAADWNyZWRlbnRpYWxfaWRtAAAACMzZODNiNDMzLTAyZjUtNGJjYy04NWNhLTdhM2QwYTgzNjI1Ym0AAAAGc2NvcGVzbQAAAAMAAAAIZnJvbV9vcHNtAAAACXRvX29iamVjdG0AAAAJdG9fYWN0aW9ubgYBy_T1yQFiAAFTgA.ABC123def456",
  "scopes": [
    "traces:write",
    "eval_runs:read",
    "eval_runs:write",
    "eval_suites:read",
    "eval_suites:write",
    "gateway:check",
    "replays:write",
    "workflow_targets:read",
    "workflow_targets:write"
  ],
  "credential_id": "3e83b433-02f5-4bcc-85ca-7a3d0a83625b",
  "expires_in": 2592000,
  "service_agent_id": "a91720d1-1c45-4343-bb45-786e20432f04",
  "workspace_id": "e65ef764-9b2c-4e24-b918-99c7be33506a"
}

{
  "detail": "api_key_revoked",
  "status": 401,
  "title": "Unauthorized",
  "type": "https://robotscenter.net/problems/unauthorized"
}

{
  "detail": "This workspace is frozen. Machine traffic is refused until the freeze is lifted.",
  "error": "workspace_frozen",
  "status": 403,
  "title": "Forbidden",
  "type": "https://robotscenter.net/problems/forbidden"
}

{
  "user": {
    "id": "7c2f0a11-4b8e-4d3a-9f21-0c1b2a3d4e5f",
    "name": "Ops",
    "email": "ops@example.com",
    "confirmed_at": null
  },
  "api_key": {
    "type": "api_key",
    "key": "agk_abc123.def456",
    "scopes": [
      "traces:write",
      "gateway:check"
    ],
    "credential_id": "3e83b433-02f5-4bcc-85ca-7a3d0a83625b",
    "service_agent_id": "a91720d1-1c45-4343-bb45-786e20432f04"
  },
  "access_token": {
    "type": "bearer",
    "token": "SFMyNTY.example.access-token",
    "scopes": [
      "traces:write",
      "gateway:check"
    ],
    "credential_id": "3e83b433-02f5-4bcc-85ca-7a3d0a83625b",
    "expires_in": 2592000,
    "service_agent_id": "a91720d1-1c45-4343-bb45-786e20432f04"
  },
  "service_agent": {
    "id": "a91720d1-1c45-4343-bb45-786e20432f04",
    "name": "Default agent",
    "status": "active",
    "slug": "default-agent"
  },
  "workspace": {
    "id": "e65ef764-9b2c-4e24-b918-99c7be33506a",
    "name": "Example Workspace",
    "status": "active",
    "plan": "starter",
    "slug": "example-workspace"
  }
}

{
  "scopes": [
    "sockets:connect",
    "events:read",
    "agent_commands:read"
  ],
  "socket_path": "/socket",
  "expires_in": 600,
  "service_agent_id": "a91720d1-1c45-4343-bb45-786e20432f04",
  "workspace_id": "e65ef764-9b2c-4e24-b918-99c7be33506a",
  "socket_token": "SFMyNTY.g3QAAAABbQAAAA1jcmVkZW50aWFsX2lkbQAAACQzZTgzYjQzMy0wMmY1LTRiY2MtODVjYS03YTNkMGE4MzYyNWJtAAAAAXMAAAANc29ja2V0X3Njb3Blc20AAAABAAAAD3NvY2tldHM6Y29ubmVjdA.a1b2c3d4"
}

{
  "detail": "This workspace is frozen. Machine traffic is refused until the freeze is lifted.",
  "error": "workspace_frozen",
  "status": 403,
  "title": "Forbidden",
  "type": "https://robotscenter.net/problems/forbidden"
}

{
  "detail": "This workspace is frozen. Machine traffic is refused until the freeze is lifted.",
  "error": "workspace_frozen",
  "status": 403,
  "title": "Forbidden",
  "type": "https://robotscenter.net/problems/forbidden"
}