LIlightsparkdev
Agent Management

Redeem device code

Changed on

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.

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

Request body

codestring required

The device code.

Example request

{
  "code": "jqzJR3AgI9OAwb_enypARw"
}

Response

Device code redeemed successfully

agentIdstring required

The agent's system-generated ID.

agentNamestring required

The agent's name.

accessTokenstring 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 response

{
  "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000001",
  "agentName": "Payroll Automation Agent",
  "accessToken": "gat_ed0ad25881e234cc28fb2dec0a4fe64e4172a3b9",
  "policy": {
    "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",
          "perTransactionLimit": 10000
        }
      ]
    },
    "approvalThresholds": {
      "currency": "USD",
      "amount": 100000
    }
  }
}

Changes

  • d996ddfb9d2bRevision changes
    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

  • 5abf2bb56bcbRevision changes
    • warning

      added the new CORRIDOR_UNDER_MAINTENANCE enum value to the response property for the response status