Redeem device code

Redeem a device code to obtain agent credentials. This endpoint is called by the agent software during installation. On success, returns a Bearer access token that the agent uses for all subsequent API calls. The token is returned only once and must be stored securely. This endpoint does not require platform authentication — the device code itself serves as proof of authorization. A code can be redeemed only once and only before its expiresAt. Redemption is rate limited. A caller over the limit receives 429 with RATE_LIMITED and a Retry-After header, and should wait that long before retrying. If the limit cannot be checked, the call is also rejected with 429.

POST /agents/device-codes/redeem

Redeem device code

cURL

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/agents/device-codes/redeem \
  --header 'Content-Type: application/json' \
  --data '
{
  "code": "jqzJR3AgI9OAwb_enypARw"
}
'

200

{
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000001",
  "agentName": "Payroll Automation Agent",
  "accessToken": "gat_ed0ad25881e234cc28fb2dec0a4fe64e4172a3b9",
  "policy": {
    "permissions": [
      "VIEW_TRANSACTIONS"
    ],
    "defaultExecutionMode": "AUTO",
    "spendingLimits": {
      "currency": "USD",
      "perTransactionLimit": 50000,
      "dailyLimit": 500000,
      "dailyTransactionLimit": 10,
      "monthlyLimit": 5000000
    },
    "accountRestrictions": {
      "allowedAccountIds": [
        "Account:019542f5-b3e7-1d02-0000-000000000001"
      ],
      "accountRules": [
        {
          "accountId": "Account:019542f5-b3e7-1d02-0000-000000000001",
          "executionMode": "AUTO",
          "perTransactionLimit": 10000
        }
      ]
    },
    "approvalThresholds": {
      "currency": "USD",
      "amount": 100000
    }
  }
}

Body

application/json

code · string · required

The device code.

Example:

"jqzJR3AgI9OAwb_enypARw"

Response

200

application/json

Device code redeemed successfully

agentId · string · required

The agent's system-generated ID.

Example:

"Agent:019542f5-b3e7-1d02-0000-000000000001"

agentName · string · required

The agent's name.

Example:

"Payroll Automation Agent"

accessToken · string · required

Bearer token used to authenticate all subsequent API calls as this agent. Pass as Authorization: Bearer <accessToken>. This token is returned only once and must be stored securely — it cannot be retrieved again.

Example:

"gat_ed0ad25881e234cc28fb2dec0a4fe64e4172a3b9"

policy · object · required

Policy governing what an agent can do, how it executes actions, and its spending boundaries.

Show child attributes