--- title: "Redeem device code" method: POST path: "/agents/device-codes/redeem" tags: ["Agent Management"] --- # Redeem device code `POST /agents/device-codes/redeem` ## Request - Base URL: `https://api.lightspark.com/grid/2025-10-13` - URL: `https://api.lightspark.com/grid/2025-10-13/agents/device-codes/redeem` - Auth: none required 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 in fixed 60-second windows. Calls without platform credentials are limited to 10 per client IP address and 1,000 across all such callers; calls made with platform credentials are limited to 600 per platform instead. A caller over a limit receives `429` with `RATE_LIMITED` and should back off until the window resets before retrying. If the limit cannot be checked, the call is also rejected with `429`. ## Request body - AgentDeviceCodeRequest - `code` string, required: The device code. ## Response `200` Device code redeemed successfully - AgentDeviceCodeRedeemResponse - `agentId` string, required: The agent's system-generated ID. - `agentName` string, required: The agent's name. - `accessToken` string, required: Bearer token used to authenticate all subsequent API calls as this agent. Pass as `Authorization: Bearer `. This token is returned only once and must be stored securely — it cannot be retrieved again. - `policy` AgentPolicy, required: Policy governing what an agent can do, how it executes actions, and its spending boundaries. - `permissions` AgentPermission[], required: List of permissions granted to the agent. - `defaultExecutionMode` 'AUTO' | 'APPROVAL_REQUIRED', required: Execution mode controlling whether agent actions require human approval. AUTO: The agent can execute actions autonomously without explicit approval. APPROVAL_REQUIRED: All agent actions require explicit human approval before execution. - `spendingLimits` AgentSpendingLimits, required: Spending limits that cap the agent's transaction amounts and frequency. They cover both the agent's sends and purchases on cards issued for the agent. All amount fields are integers in the smallest unit of the specified currency. When a transaction is denominated in a different currency, Grid converts using the exchange rate at evaluation time. - `currency` string, required: ISO 4217 currency code that all amount limits are denominated in. This currency is immutable after the agent is created. - `perTransactionLimit` integer, required: Maximum amount of a single send or card authorization. - `dailyLimit` integer, nullable: Maximum total the agent can send and spend on its cards per day. Null means no daily limit. - `dailyTransactionLimit` integer: Maximum number of sends and card authorizations the agent can make per day. - `monthlyLimit` integer, nullable: Maximum total the agent can send and spend on its cards per month. Null means no monthly limit. - `accountRestrictions` AgentAccountRestrictions: Optional restrictions that limit the agent to specific accounts or override policy per account. - `allowedAccountIds` string[], nullable: If set, restricts the agent to operate only on the specified internal account IDs. Null means the agent can access all accounts. - `accountRules` AgentAccountRule[]: Per-account rules that override the agent's default policy for specific accounts. - `accountId` string, required: The internal account ID this rule applies to. - `executionMode` 'AUTO' | 'APPROVAL_REQUIRED': Execution mode controlling whether agent actions require human approval. AUTO: The agent can execute actions autonomously without explicit approval. APPROVAL_REQUIRED: All agent actions require explicit human approval before execution. - `perTransactionLimit` integer, nullable: Per-transaction limit override, in the smallest unit of the policy's `spendingLimits.currency`. Null inherits from the agent's spending limits. - `approvalThresholds` AgentApprovalThresholds: Thresholds that force approval for high-value transactions, overriding the default execution mode. The threshold currency must equal the policy's spending limits currency. When a transaction is denominated in a different currency, Grid converts it to the policy currency at evaluation time. - `currency` string: ISO 4217 currency code that the amount threshold is denominated in. Required when amount is set and must equal `spendingLimits.currency`. - `amount` integer, nullable: If set, any transaction above this amount (in the smallest unit of the specified currency) will require explicit approval even when the agent's defaultExecutionMode is AUTO. Null means no threshold override. ## Other responses - `400`: Bad request (e.g., code already redeemed or expired) - `403`: Forbidden - Agents API is not enabled for the platform - `404`: Device code not found - `429`: Too many requests. Returned with `RATE_LIMITED`. - `500`: Internal service error ## Changes > 115 revisions in range; 2 not diffed. - **2026-10-28** `d996ddfb9d2b`: 5 info - added the optional property `details/missingFields` to the response with the `400` status - added the optional property `details/permission` to the response with the `403` status - added the optional property `details/policyDenialReason` to the response with the `403` status - added the optional property `details/refusalReason` to the response with the `400` status - …1 more - **2026-10-28** `5abf2bb56bcb`: 1 warning - added the new `CORRIDOR_UNDER_MAINTENANCE` enum value to the `code` response property for the response status `403` - **2026-10-24** `715332dcb111`: 1 warning - added the new `EXACT_AMOUNT_UNAVAILABLE` enum value to the `code` response property for the response status `400` - **2026-10-20** `761d1d030cb5`: 2 warning - added the new `CARDHOLDER_AGREEMENT_NOT_ACCEPTED` enum value to the `code` response property for the response status `400` - added the new `ISSUE_CARDS` enum value to the `policy/permissions/items/` response property for the response status `200` - **2026-10-18** `add40cac0f84`: 1 warning - added the new `DESTINATION_NOT_ALLOWED` enum value to the `code` response property for the response status `403` [Operation history](https://skmtc.dev/lightsparkdev/apis/grid-api/changes/agents/device-codes/redeem/post.md) --- [API](https://skmtc.dev/lightsparkdev/apis/grid-api.md) - [All operations](https://skmtc.dev/lightsparkdev/apis/grid-api/llms.txt) - [OpenAPI document](https://skmtc.dev/lightsparkdev/apis/grid-api/revisions/7a1db46ec552?raw)