Let an agent use a stored card

curl --request PUT \
  --url https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards/{storedCardId}/agents/{agentId} \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'PUT', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards/{storedCardId}/agents/{agentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards/{storedCardId}/agents/{agentId}")
  .put(null)
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

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

{
  "lastFour": "0005",
  "brand": "VISA",
  "funding": "CREDIT",
  "expiryMonth": 8,
  "expiryYear": 2029,
  "id": "StoredCard:019542f5-b3e7-1d02-0000-000000000077",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
  "status": "ACTIVE",
  "holderName": "Jane Doe",
  "agentIds": [
    "Agent:019542f5-b3e7-1d02-0000-000000000042"
  ],
  "createdAt": "2026-11-06T15:00:00Z",
  "updatedAt": "2026-11-06T15:00:00Z",
  "issuerCountry": "US",
  "nickname": "Personal Visa",
  "billingAddress": {
    "line1": "123 Main Street",
    "postalCode": "94105",
    "country": "US",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA"
  },
  "autoApprovals": [
    {
      "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
      "merchant": "example-store.com",
      "maxAmount": 4999,
      "currency": "USD"
    }
  ],
  "removedAt": "2026-11-07T09:30: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"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

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

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

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

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

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

Agent Management

Let an agent use a stored card

Let one of the customer’s own agents use this card. The agent also needs the USE_STORED_CARDS permission, which is never granted by default. Every use still waits for the customer’s approval unless they choose to auto-approve a merchant. Granting access is a grant of spending power on the customer’s own card: confirm it with the customer (for example with a passkey or an emailed code) before calling. Granting an agent that already has access succeeds and changes nothing.

PUT

customers

{customerId}

stored-cards

{storedCardId}

agents

{agentId}

Let an agent use a stored card

curl --request PUT \
  --url https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards/{storedCardId}/agents/{agentId} \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'PUT', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards/{storedCardId}/agents/{agentId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

val client = OkHttpClient()

val request = Request.Builder()
  .url("https://api.lightspark.com/grid/2025-10-13/customers/{customerId}/stored-cards/{storedCardId}/agents/{agentId}")
  .put(null)
  .addHeader("Authorization", "Basic <encoded-value>")
  .build()

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

{
  "lastFour": "0005",
  "brand": "VISA",
  "funding": "CREDIT",
  "expiryMonth": 8,
  "expiryYear": 2029,
  "id": "StoredCard:019542f5-b3e7-1d02-0000-000000000077",
  "customerId": "Customer:019542f5-b3e7-1d02-0000-000000000010",
  "status": "ACTIVE",
  "holderName": "Jane Doe",
  "agentIds": [
    "Agent:019542f5-b3e7-1d02-0000-000000000042"
  ],
  "createdAt": "2026-11-06T15:00:00Z",
  "updatedAt": "2026-11-06T15:00:00Z",
  "issuerCountry": "US",
  "nickname": "Personal Visa",
  "billingAddress": {
    "line1": "123 Main Street",
    "postalCode": "94105",
    "country": "US",
    "line2": "Apt 4B",
    "city": "San Francisco",
    "state": "CA"
  },
  "autoApprovals": [
    {
      "agentId": "Agent:019542f5-b3e7-1d02-0000-000000000042",
      "merchant": "example-store.com",
      "maxAmount": 4999,
      "currency": "USD"
    }
  ],
  "removedAt": "2026-11-07T09:30: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"
    ],
    "refusalReason": "AGENT_POLICY_DENIED",
    "missingFields": [
      "PHONE_NUMBER"
    ]
  }
}

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

{
  "code": "FORBIDDEN",
  "reason": "<string>",
  "details": {
    "refusalReason": "AGENT_POLICY_DENIED",
    "permission": "ISSUE_CARDS",
    "policyDenialReason": "DAILY_LIMIT_EXCEEDED"
  }
}

{
  "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>

Path Parameters

customerId

string

required

System-generated unique customer identifier

storedCardId

string

required

System-generated unique stored card identifier

agentId

string

required

System-generated unique agent identifier

Response

Access granted

A card the customer already owns, stored so their agents can use it. Grid holds the card number only as Evervault ciphertext: no Grid system stores, logs or returns the number itself.

lastFour

string

required

Last four digits of the card number.

Required string length: 4

Pattern: ^[0-9]{4}$

Example:

"0005"

brand

string

required

The card network, from the issuer's BIN data. Known values: VISA, MASTERCARD, AMERICAN_EXPRESS, DISCOVER, DINERS_CLUB, JCB, UNIONPAY, UNKNOWN. Treat an unrecognized value as UNKNOWN rather than an error.

Maximum string length: 32

Example:

"VISA"

funding

string

required

How the card is funded, from the issuer's BIN data. Known values: CREDIT, DEBIT, PREPAID, CHARGE, DEFERRED_DEBIT, UNKNOWN. Treat an unrecognized value as UNKNOWN rather than an error.

Maximum string length: 32

Example:

"CREDIT"

expiryMonth

integer

required

Expiry month, 1 to 12.

Required range: 1 <= x <= 12

Example:

8

expiryYear

integer

required

Four-digit expiry year.

Required range: 2000 <= x <= 2199

Example:

2029

string

required

System-generated unique identifier of the stored card.

Maximum string length: 64

Example:

"StoredCard:019542f5-b3e7-1d02-0000-000000000077"

customerId

string

required

The customer who owns the card.

Maximum string length: 64

Example:

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

status

enum<string>

required

Status	Description
`ACTIVE`	The card can be used by the agents it is shared with
`REMOVED`	The customer removed the card. Grid erased its encrypted number, holder name and billing address; only the display fields remain

Available options:

ACTIVE,

REMOVED

holderName

string

required

The cardholder name, as the customer entered it. Empty once the card is REMOVED.

Maximum string length: 255

Example:

"Jane Doe"

agentIds

string[]

required

The agents the customer allowed to use this card. An agent also needs the USE_STORED_CARDS permission. Empty once the card is REMOVED.

Maximum array length: 100

Maximum string length: 64

createdAt

string<date-time>

required

When the card was stored.

Example:

"2026-11-06T15:00:00Z"

updatedAt

string<date-time>

required

When the card was last changed.

Example:

"2026-11-06T15:00:00Z"

issuerCountry

string

ISO 3166-1 alpha-2 country of the card's issuer, when the BIN data names one.

Required string length: 2

Example:

"US"

nickname

string

The customer's own label for the card.

Maximum string length: 64

Example:

"Personal Visa"

billingAddress

object

The card's billing address. Absent once the card is REMOVED.

Show child attributes

autoApprovals

object[]

Merchants where the customer chose to let an agent use the card without asking again, each up to an amount. Cleared for an agent when its access is removed. Empty once the card is REMOVED.

Maximum array length: 100

Show child attributes

removedAt

string<date-time>

When the customer removed the card. Present only once it is REMOVED.

Example:

"2026-11-07T09:30:00Z"

Using the API

API documentation

Let an agent use a stored card

Authorizations

Path Parameters

Response