---
title: "Redeem device code"
method: POST
path: "/agents/device-codes/{code}/redeem"
tags: ["Agent Management"]
---

# Redeem device code

`POST /agents/device-codes/{code}/redeem`

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.

## 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 <accessToken>`. 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. 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.
      - `perTransactionLimit` integer, required — Maximum amount the agent can transfer in a single transaction.
      - `dailyLimit` integer, nullable — Maximum total amount the agent can transfer per day. Null means no daily limit.
      - `dailyTransactionLimit` integer — Maximum number of transactions the agent can initiate per day.
      - `monthlyLimit` integer, nullable — Maximum total amount the agent can transfer 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 relevant currency. Null inherits from the agent's spending limits.
    - `approvalThresholds` AgentApprovalThresholds — Thresholds that force approval for high-value transactions, overriding the default execution mode. When a transaction is denominated in a different currency than the threshold, Grid converts using the exchange rate at evaluation time.
      - `currency` string — ISO 4217 currency code that the amount threshold is denominated in. Required when amount is set.
      - `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)
- `404` — Device code not found
- `500` — Internal service error

---

[API](https://skmtc.net/stainless-api/apis/grid-api.md) · [All operations](https://skmtc.net/stainless-api/apis/grid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stainless-api/grid-api/versions/526036c12609/schema)