Create a delegated signing key

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/auth/delegated-keys \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "internalAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "nickname": "Card payments key"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cardId: 'Card:019542f5-b3e7-1d02-0000-000000000010',
    internalAccountId: 'InternalAccount:019542f5-b3e7-1d02-0000-000000000002',
    nickname: 'Card payments key'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/auth/delegated-keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"cardId\": \"Card:019542f5-b3e7-1d02-0000-000000000010\",\n  \"internalAccountId\": \"InternalAccount:019542f5-b3e7-1d02-0000-000000000002\",\n  \"nickname\": \"Card payments key\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/auth/delegated-keys")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "DelegatedKey:019542f5-b3e7-1d02-0000-000000000021",
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "fundingSourceId": "CardFundingSource:019542f5-b3e7-1d02-0000-000000000011",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "publicKey": "02a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "nickname": "Card payments key",
  "status": "ACTIVE",
  "createdAt": "2026-04-08T15:30:01Z",
  "updatedAt": "2026-04-08T15:30:42Z"
}

{
  "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"userId\":\"user_2m9F...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_EXAMPLE\"}",
  "requestId": "Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21",
  "expiresAt": "2026-04-08T15:35:00Z"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Embedded Wallet Auth

Create a delegated signing key

Delegate Spark token-transaction signing authority for a card funding source or agent backed by an Embedded Wallet internal account to a Grid-custodied P-256 API key. Grid uses the requested owner and internal account to identify the wallet, generates the keypair server-side, creates an isolated signer identity holding the public key, then policies granting that identity signing and self-revocation authority. The private key is custodied by Grid and never returned. Both activities must be authorized by the wallet owner, so creation is a three-leg signed-retry flow:

Call POST /auth/delegated-keys with no signature headers. Grid generates the delegated keypair and the response is 202 with a payloadToSign, requestId, and expiresAt.
Use the session API keypair of a verified credential on the requested Embedded Wallet internal account to build an API-key stamp over payloadToSign, then retry the same request with that full stamp as the Grid-Wallet-Signature header and the requestId echoed back as the Request-Id header. The response is a second 202 with a new payloadToSign, requestId, and expiresAt.
Stamp the new payloadToSign with the same session keypair and retry once more with the new Request-Id. The signed retry returns 201 with the created DelegatedKey in ACTIVE status. For card keys, a provisioned PENDING_AUTH card using this funding source becomes ACTIVE automatically. Cards still provisioning remain PROCESSING; frozen and closed cards retain their status.

The same request body must be sent on all three legs. A flow abandoned after the second leg leaves the key in PENDING status: the signer identity exists but holds no policies, so it cannot sign or revoke itself. Abandoned PENDING keys do not block creating another delegated key. After activation, Grid uses the custodied key to authorize signing for the card’s Embedded Wallet funding account or for policy-approved agent actions in place of a session keypair; the platform never handles the key material.

Each card funding source, or each agent and Embedded Wallet pair, may have at most one ACTIVE delegated key; revoke the existing active key before creating a new one. A delegated key authorizes raw-payload signing for the wallet and cannot be scoped to amounts or recipients by the public API. Revoke it with DELETE /auth/delegated-keys/{id} when no longer needed.

POST

auth

delegated-keys

Create a delegated signing key

curl --request POST \
  --url https://api.lightspark.com/grid/2025-10-13/auth/delegated-keys \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "internalAccountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "nickname": "Card payments key"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cardId: 'Card:019542f5-b3e7-1d02-0000-000000000010',
    internalAccountId: 'InternalAccount:019542f5-b3e7-1d02-0000-000000000002',
    nickname: 'Card payments key'
  })
};

fetch('https://api.lightspark.com/grid/2025-10-13/auth/delegated-keys', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val mediaType = MediaType.parse("application/json")
val body = RequestBody.create(mediaType, "{\n  \"cardId\": \"Card:019542f5-b3e7-1d02-0000-000000000010\",\n  \"internalAccountId\": \"InternalAccount:019542f5-b3e7-1d02-0000-000000000002\",\n  \"nickname\": \"Card payments key\"\n}")
val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/auth/delegated-keys")
  .post(body)
  .addHeader("Authorization", "Basic <encoded-value>")
  .addHeader("Content-Type", "application/json")
  .build()

val response = client.newCall(request).execute()

{
  "id": "DelegatedKey:019542f5-b3e7-1d02-0000-000000000021",
  "cardId": "Card:019542f5-b3e7-1d02-0000-000000000010",
  "fundingSourceId": "CardFundingSource:019542f5-b3e7-1d02-0000-000000000011",
  "accountId": "InternalAccount:019542f5-b3e7-1d02-0000-000000000002",
  "publicKey": "02a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90",
  "nickname": "Card payments key",
  "status": "ACTIVE",
  "createdAt": "2026-04-08T15:30:01Z",
  "updatedAt": "2026-04-08T15:30:42Z"
}

{
  "payloadToSign": "{\"organizationId\":\"org_2m9F...\",\"parameters\":{\"userId\":\"user_2m9F...\"},\"timestampMs\":\"1775681700000\",\"type\":\"ACTIVITY_TYPE_EXAMPLE\"}",
  "requestId": "Request:7c4a8d09-ca37-4e3e-9e0d-8c2b3e9a1f21",
  "expiresAt": "2026-04-08T15:35:00Z"
}

{
  "code": "INVALID_INPUT",
  "reason": "<string>",
  "details": {
    "errors": [
      {
        "field": "identifier",
        "constraint": {
          "format": "email",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "enum": [
            "SSN",
            "ITIN",
            "NON_US_TAX_ID"
          ],
          "minLength": 1,
          "maxLength": 500
        },
        "message": "Value is not one of the allowed enum members."
      }
    ],
    "missingRequirements": [
      "SUPPORTING_PROOF"
    ]
  }
}

{
  "code": "UNAUTHORIZED",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_FOUND",
  "reason": "<string>",
  "details": {}
}

{
  "code": "TRANSACTION_NOT_PENDING_PLATFORM_APPROVAL",
  "reason": "<string>",
  "details": {}
}

{
  "code": "GRID_SWITCH_ERROR",
  "reason": "<string>",
  "details": {}
}

Authorizations

Authorization

string

header

required

API token authentication using format <api token id>:<api client secret>

Headers

Grid-Wallet-Signature

string

Full API-key stamp built over the prior payloadToSign with the session API keypair of a verified credential on the same internal account. Required on the signed retries; ignored on the initial call.

Request-Id

string

The requestId returned in the prior 202 response, echoed back exactly on the signed retry so the server can correlate it with the issued challenge. Required on the signed retries; must be paired with Grid-Wallet-Signature.

Body

application/json

Creates a delegated signing key for a card funding source or an agent. Exactly one of cardId or agentId is required. Requests that provide both fields or neither field return a 400 response.

internalAccountId

string

required

The id of the Embedded Wallet internal account this key may sign for. For a card key, Grid uses the (cardId, internalAccountId) pair to find the active card funding-source binding. For an agent key, the account must belong to the agent's customer.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

nickname

string

required

Human-readable label for the delegated key.

Required string length: 1 - 256

Example:

"Payments key"

cardId

string

The id of the card whose Embedded Wallet funding account will use this delegated signing key. Omit when creating a key for an agent.

Example:

"Card:019542f5-b3e7-1d02-0000-000000000010"

agentId

string

The id of the agent that will use this delegated signing key. The agent must belong to the customer that owns the Embedded Wallet internal account. Omit when creating a key for a card.

Example:

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

Response

Delegated key created and policy granted. The key is ACTIVE and Grid may use it to stamp card-payment quote executions or policy-approved actions for the selected agent.

A delegated signing key for either a card funding source or an agent, backed by an Embedded Wallet internal account. Card keys include cardId and fundingSourceId; agent keys include agentId. Returned from POST /auth/delegated-keys (on activation), GET /auth/delegated-keys (list), and GET /auth/delegated-keys/{id}. The keypair is generated and custodied by Grid; the private key is never returned. While ACTIVE, Grid may use the key to authorize Spark token-transaction signing for the selected card funding source or agent in place of a session keypair. publicKey is informational metadata identifying the credential.

string

required

Grid-issued DelegatedKey:<uuid> identifier.

Example:

"DelegatedKey:019542f5-b3e7-1d02-0000-000000000021"

accountId

string

required

The Embedded Wallet internal account this key is delegated for, derived from the card funding source or the agent's customer.

Example:

"InternalAccount:019542f5-b3e7-1d02-0000-000000000002"

publicKey

string

required

Compressed P-256 public key (hex) of the delegated API keypair.

Example:

"02a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8f90"

nickname

string

required

Human-readable label for the delegated key.

Example:

"Settlement service key"

status

enum<string>

required

Status of a delegated signing key.

PENDING: The delegated user exists but the policy-creation leg never completed. The key cannot sign.
ACTIVE: The policy is granted and the key may stamp quote executions.
REVOKED: The delegated user has been deleted and the key can no longer sign.

Available options:

PENDING,

ACTIVE,

REVOKED

Example:

"ACTIVE"

createdAt

string<date-time>

required

When the delegated key was created.

Example:

"2026-04-08T15:30:01Z"

updatedAt

string<date-time>

required

When the delegated key was last updated.

Example:

"2026-04-08T15:30:42Z"

cardId

string

The card this key is delegated for. Present only for card keys.

Example:

"Card:019542f5-b3e7-1d02-0000-000000000010"

fundingSourceId

string

The card funding source this key is delegated for. Present only for card keys.

Example:

"CardFundingSource:019542f5-b3e7-1d02-0000-000000000011"

agentId

string

The agent this key is delegated for. Present only for agent keys.

Example:

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

Using the API

API documentation

Create a delegated signing key

Authorizations

Headers

Body

Response