Instructions
DEPRECATED

This API is deprecated and remains available for existing integrations. New integrations should use allowances. No removal date has been announced.

Instructions define spending rules for a purchase. Each instruction is tied to an enrollment and specifies an amount, description, and expiration. The consumer must verify the instruction before virtual card credentials can be retrieved.

Authentication

All requests require a BT-API-KEY header with your Basis Theory API key.

All errors follow the standard error response format.

List Instructions

Returns a paginated list of instructions for an agent.

GET

https://api.basistheory.com/agentic/agents/{agent_id}/instructions

Permissions

agent:instruction:get

Request

curl 'https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions?limit=25' \
  -H 'BT-API-KEY: <BT_API_KEY>'

Request Parameters

Attribute	Required	Type	Description
`agent_id`	Yes	string	The ID of the agent
`enrollment_id`	No	string	Filter instructions by enrollment ID
`limit`	No	integer	Number of results to return (default: 25, max: 100)
`cursor`	No	string	Opaque pagination cursor from a previous response

Response

Returns a paginated list of instruction objects.

{
  "data": [
    {
      "id": "ins_luPDv2xm3Yb8RjFJz9oTC",
      "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
      "status": "approved",
      "amount": {
        "value": "500.00",
        "currency": "USD"
      },
      "expires_at": "2030-02-20T00:00:00Z",
      "created_at": "2026-01-15T10:35:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6Imluc19sdVBEdjJ4bTNZYjhSakZKejlvVEMifQ",
    "has_more": true
  }
}

Create Instruction

Creates a new purchase instruction for an enrollment.

POST

https://api.basistheory.com/agentic/agents/{agent_id}/instructions

Permissions

agent:instruction:create

Request

curl -X POST https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
    "amount": {
      "value": "500.00",
      "currency": "USD"
    },
    "description": "Purchase electronics",
    "expires_at": "2030-02-20T00:00:00Z"
  }'

Request Parameters

Attribute	Required	Type	Description
`agent_id`	Yes	string	The ID of the agent
`enrollment_id`	Yes	string	The ID of the enrollment to create the instruction for
`amount`	Yes	object	The amount object defining the spending limit
`description`	Yes	string	A description of the purchase. Used as the display name shown to the cardholder during passkey verification when `merchant.name` is not provided.
`expires_at`	Yes	string	ISO 8601 timestamp for when the instruction expires
`merchant`	No	object	The merchant object for this purchase. If provided, it is stored on the instruction and used as the default when retrieving credentials. When `merchant.name` is provided, it is displayed to the cardholder during passkey verification instead of `description`.
`recurring`	No	object	Recurring schedule. See recurring object
`instance_details`	No	object	Device information. See instance details

Amount Object

Attribute	Required	Type	Description
`value`	Yes	string	The monetary amount as a decimal string (e.g., `"500.00"`)
`currency`	No	string	ISO 4217 currency code (default: `USD`)

Recurring Object

Attribute	Required	Type	Description
`frequency`	Yes	string	Recurring frequency: `weekly`, `monthly`, or `yearly`

Response

Returns an instruction object if successful. The instruction will have pending_verification status until the consumer completes verification.

{
  "id": "ins_luPDv2xm3Yb8RjFJz9oTC",
  "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
  "status": "pending_verification",
  "amount": {
    "value": "500.00",
    "currency": "USD"
  },
  "expires_at": "2030-02-20T00:00:00Z",
  "created_at": "2026-01-15T10:35:00Z"
}

Get Instruction

Retrieves an instruction by ID.

GET

https://api.basistheory.com/agentic/agents/{agent_id}/instructions/{instruction_id}

Permissions

agent:instruction:get

Request

curl https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions/ins_luPDv2xm3Yb8RjFJz9oTC \
  -H 'BT-API-KEY: <BT_API_KEY>'

Request Parameters

Attribute	Required	Type	Description
`agent_id`	Yes	string	The ID of the agent
`instruction_id`	Yes	string	The ID of the instruction to retrieve

Response

Returns an instruction object if successful.

{
  "id": "ins_luPDv2xm3Yb8RjFJz9oTC",
  "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
  "status": "approved",
  "amount": {
    "value": "500.00",
    "currency": "USD"
  },
  "expires_at": "2030-02-20T00:00:00Z",
  "created_at": "2026-01-15T10:35:00Z"
}

Update Instruction

Updates an existing instruction.

PATCH

https://api.basistheory.com/agentic/agents/{agent_id}/instructions/{instruction_id}

Permissions

agent:instruction:update

Request

curl -X PATCH https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions/ins_luPDv2xm3Yb8RjFJz9oTC \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": {
      "value": "750.00",
      "currency": "USD"
    },
    "expires_at": "2030-03-20T00:00:00Z"
  }'

Request Parameters

Attribute	Required	Type	Description
`agent_id`	Yes	string	The ID of the agent
`instruction_id`	Yes	string	The ID of the instruction to update
`amount`	No	object	Updated amount object
`expires_at`	No	string	Updated ISO 8601 expiration timestamp

Response

Returns the updated instruction object if successful.

{
  "id": "ins_luPDv2xm3Yb8RjFJz9oTC",
  "enrollment_id": "enr_wNe75VKdzvojI9iD5fJxr",
  "status": "approved",
  "amount": {
    "value": "750.00",
    "currency": "USD"
  },
  "expires_at": "2030-03-20T00:00:00Z",
  "created_at": "2026-01-15T10:35:00Z"
}

Delete Instruction

Deletes an instruction.

DELETE

https://api.basistheory.com/agentic/agents/{agent_id}/instructions/{instruction_id}

Permissions

agent:instruction:delete

Request

curl -X DELETE https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions/ins_luPDv2xm3Yb8RjFJz9oTC \
  -H 'BT-API-KEY: <BT_API_KEY>'

Request Parameters

Attribute	Required	Type	Description
`agent_id`	Yes	string	The ID of the agent
`instruction_id`	Yes	string	The ID of the instruction to delete

Response

Returns a 204 No Content response if successful.

Errors: 404 INSTRUCTION_NOT_FOUND, 500 PROVIDER_INSTRUCTION_CANCEL_FAILED.

Verify Instruction

Instruction verification is a multi-step flow that requires the consumer to authenticate via passkey. The @basis-theory/react-agentic SDK handles this flow automatically via the verifyInstruction() method. The individual endpoints are documented below for reference.

For an existing integration, use the verifyInstruction() method from the @basis-theory/react-agentic SDK's useAgentic hook. It handles the passkey authentication UI. See the deprecated integration guide for usage examples.

Verification Flow

Start verification — POST /agents/:id/instructions/:id/verify — initiates passkey challenge.
Submit passkey — POST /agents/:id/instructions/:id/verify/passkey — submits the passkey assertion.

Start Verification

Initiates the instruction verification flow.

POST

https://api.basistheory.com/agentic/agents/{agent_id}/instructions/{instruction_id}/verify

Permissions

agent:instruction:verify

curl -X POST https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions/ins_luPDv2xm3Yb8RjFJz9oTC/verify \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "device_context": {
      "screen_height": 1080,
      "screen_width": 1920,
      "user_agent_string": "Mozilla/5.0 ...",
      "language_code": "en-US",
      "time_zone": "America/New_York",
      "java_script_enabled": true,
      "client_device_id": "a1b2c3d4e5f6a1b2c3d4e5f6",
      "client_reference_id": "550e8400-e29b-41d4-a716-446655440000",
      "platform_type": "WEB"
    }
  }'

The device context object uses the same schema as enrollment verification.

Returns either { "status": "verified" } if passkeys are bypassed, or a challenge response for passkey authentication.

Submit Passkey

Submits the passkey/FIDO assertion to complete instruction verification.

POST

https://api.basistheory.com/agentic/agents/{agent_id}/instructions/{instruction_id}/verify/passkey

Permissions

agent:instruction:verify

curl -X POST https://api.basistheory.com/agentic/agents/agt_fukICjsY2xzRCECiTCbKM/instructions/ins_luPDv2xm3Yb8RjFJz9oTC/verify/passkey \
  -H 'BT-API-KEY: <BT_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "assurance_data": {
      "identifier": "<IDENTIFIER>",
      "dfp_session_id": "<DFP_SESSION_ID>",
      "fido_assertion_data": { "code": "<FIDO_ASSERTION_CODE>" }
    }
  }'

After successful verification, the instruction status changes from pending_verification to approved. May return a PASSKEY_FAILED error if the assertion is invalid.

Instruction Object

Attribute	Type	Description
`id`	string	Unique identifier of the instruction
`enrollment_id`	string	The ID of the enrollment this instruction belongs to
`status`	string	The instruction status: `pending`, `pending_verification`, `approved`, or `cancelled`
`type`	string	The instruction type, such as `agentic`
`credential_type`	string	The credential this instruction issues, such as `card`
`amount`	object	The spending limit. See amount object
`expires_at`	string	ISO 8601 timestamp for when the instruction expires
`created_at`	string	ISO 8601 timestamp of when the instruction was created

description and recurring are accepted on create and stored, but they are not returned on any instruction response.

Instruction Statuses

Status	Description
`pending`	Awaiting provider approval
`pending_verification`	Provider approved; awaiting consumer verification via passkey
`approved`	Consumer verified; virtual card credentials can be retrieved
`cancelled`	Cancelled by the card network, for example when the underlying token is suspended

Expiry is evaluated per request rather than stored: an instruction past its expires_at still reports approved, and credential retrieval against it returns 400 INSTRUCTION_EXPIRED. A provider failure raises PROVIDER_INSTRUCTION_FAILED at create time rather than persisting a status.

Credentials can only be retrieved for instructions with approved status.

Pagination

List endpoints use cursor-based pagination.

Attribute	Type	Description
`pagination.next_cursor`	string	Opaque cursor for the next page (absent when no more results)
`pagination.has_more`	boolean	Whether there are more results beyond this page

Pass next_cursor as the cursor query parameter to retrieve the next page.

Authentication​

List Instructions​

Permissions​

Request​

Request Parameters​

Response​

Create Instruction​

Permissions​

Request​

Request Parameters​

Amount Object​

Recurring Object​

Response​

Get Instruction​

Permissions​

Request​

Request Parameters​

Response​

Update Instruction​

Permissions​

Request​

Request Parameters​

Response​

Delete Instruction​

Permissions​

Request​

Request Parameters​

Response​

Verify Instruction​

Verification Flow​

Start Verification​

Permissions​

Submit Passkey​

Permissions​

Instruction Object​

Instruction Statuses​

Pagination​

Authentication

List Instructions

Permissions

Request

Request Parameters

Response

Create Instruction

Permissions

Request

Request Parameters

Amount Object

Recurring Object

Response

Get Instruction

Permissions

Request

Request Parameters

Response

Update Instruction

Permissions

Request

Request Parameters

Response

Delete Instruction

Permissions

Request

Request Parameters

Response

Verify Instruction

Verification Flow

Start Verification

Permissions

Submit Passkey

Permissions

Instruction Object

Instruction Statuses

Pagination