Start agent login

Starts the agent approval flow and returns a short customer code plus a browser verification URL. Agents should send verificationUriComplete to the customer, wait for approval, then poll POST /api/v1/experimental/agent/auth/exchange with deviceCode. A successful exchange returns a reusable workspace API key secret in apiKey.key for the HTTP API, not an OAuth token. Effective access is the union of role permissions and explicit permissions. If neither is provided, role defaults to admin.

POST/api/v1/experimental/agent/auth/requests

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

agentName*string

a non empty string

Length1 <= length

agentDescription?string

a non empty string

Length1 <= length

workspaceHandle?string

a non empty string

Length1 <= length

apiKeyName?string

a non empty string

Length1 <= length

role?string

Hardcoded role available for new workspace API keys

Value in"admin" | "editor" | "viewer"

Example"admin"

permissions?

Explicit permissions attached directly to the API key. Effective access is the union of role permissions and these permissions.

Example

{
  "channels": [
    "read",
    "write"
  ],
  "messages": [
    "read",
    "write"
  ],
  "sessionEvents": [
    "read"
  ],
  "threads": [
    "read",
    "write"
  ]
}

apiKeyExpiresInMs?integer

a positive number

Range0 < value

loginExpiresInMs?integer

a positive number

Range0 < value

Response Body

`application/json`

curl -X POST "https://loading/api/v1/experimental/agent/auth/requests" \  -H "Content-Type: application/json" \  -d '{    "agentName": "Claude",    "agentDescription": "Needs read/write access to data and update your workspace data.",    "workspaceHandle": "acme-growth-team",    "apiKeyName": "Claude production key",    "role": "admin",    "permissions": {      "sessionEvents": [        "read"      ]    },    "apiKeyExpiresInMs": 2592000000,    "loginExpiresInMs": 900000  }'

{
  "deviceCode": "0blbPwylJ_5mAZGb29sz8Y-V3CGSHfZ0bj6c5zWd0M8",
  "userCode": "BK7H-3M9Q",
  "verificationUri": "https://andiapi.com/agent-login",
  "verificationUriComplete": "https://andiapi.com/agent-login?user_code=BK7H-3M9Q",
  "expiresAt": "2026-03-07T18:15:00.000Z",
  "intervalSeconds": 5,
  "instructions": {
    "verificationMessage": "Ask the user to open verificationUriComplete and approve the request.",
    "exchangeMessage": "After approval, call POST /api/v1/experimental/agent/auth/exchange with deviceCode.",
    "apiKeySecretField": "apiKey.key",
    "apiKeySaveHint": "When exchange succeeds, save apiKey.key immediately. The secret is returned once and should be reused for future calls."
  }
}

{
  "issues": [
    {
      "_tag": "Pointer",
      "path": [
        "string"
      ],
      "message": "string"
    }
  ],
  "message": "string",
  "_tag": "HttpApiDecodeError"
}

{
  "code": "internal_error",
  "message": "An unexpected server error occurred."
}

Start agent login

Request Body

Response Body

201application/json

400application/json

500application/json

`application/json`

`application/json`

`application/json`