> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create instruction

> Creates a purchase instruction (spending authorization) for the token's customer and returns a short-lived activation link that the user opens to approve it with a Passkey. Requires `portal:write`.

`payment_instrument_id` selects one of two signing modes:

* **Sign with an existing card**: send `payment_instrument_id`. The instruction is `CREATED`, and the activation link opens the authorization page for that card.
* **Bind a card and sign**: omit `payment_instrument_id`. The instruction is `PENDING`, and the activation link opens the card-binding and authorization flow, where the user binds a card and authorizes in one Passkey ceremony.

For the first mode, read `payment_instrument_id` from [List payment methods](https://docs.clinkbill.com/api-reference/agent-portal/list_payment_methods.md). In the second mode, do not send a card number, CVV, or any other card field; the user enters card details on the Clink page. Customer identity always comes from the token; the request body has no customer or email field.

After the activation link's signing session is exchanged, an existing-card instruction continues to `/authorize/{paymentInstrumentId}?instructionId=...`; a bind-and-sign instruction continues to `/bind-authorize?instructionId=...`, where the user binds a card and authorizes in one Passkey ceremony.

> [!WARNING]
>
> Treat the activation link as a credential. Do not forward it, screenshot it, or write it to logs; anyone who has the link can open it while it is valid and obtain a Clink browser login session for that customer. Deliver it only to the intended user.

## Activate the instruction

Creating an instruction is not an authorization. An instruction with an existing card is `CREATED`; an instruction that will bind a card is `PENDING`. Both become `ACTIVE` only after the user completes Passkey verification on Clink's page. The link can be reopened or refreshed while it is valid, but the instruction can be signed only once.

1. Send the user to `activation_url` in a browser.
2. For `CREATED`, the user reviews the card and completes Passkey verification. For `PENDING`, the user binds a card and completes Passkey verification in the same ceremony. The page establishes the browser session and continues to the authorization step.
3. Poll [`GET /agent/platform/authorizations/{instructionId}`](https://docs.clinkbill.com/api-reference/agent-portal/get_authorization) until `status` is `ACTIVE`.

If the user does not complete the flow, the instruction stays `CREATED` or `PENDING` and authorizes no spending. Only send the link to the intended user; it is an activation link, not a portal token.

## Idempotency

`request_id` is the idempotency key, and the rules are identical in both signing modes. Clink keeps the idempotency record for 24 hours by default; after that window, retrying the same `request_id` creates a new instruction. Within the window, retrying with identical parameters returns the same `instruction_id`; a normal retry on an instruction that is not yet signed returns a fresh activation link. If the retried `request_id` refers to an instruction that is already signed or final, Clink returns the instruction without a new `activation_url` or `activation_expires_at` (both fields are omitted); read [`GET /agent/platform/authorizations/{instructionId}`](https://docs.clinkbill.com/api-reference/agent-portal/get_authorization) for the current status. Reusing a `request_id` with different parameters returns `409` with `code` `71211011` (`portal_conflict`).


## OpenAPI

````yaml POST /agent/platform/authorizations
openapi: 3.1.0
info:
  title: Clink Agent Portal API
  description: >-
    Agent Portal APIs let an Agent platform read and manage one user's Clink
    account with a portal user token: payment methods, orders, refunds, purchase
    instructions, payment credentials, payment results, and settings.
  version: 1.0.0
servers:
  - url: https://uat-api.clinkbill.com
    description: Sandbox
security:
  - PortalToken: []
paths:
  /agent/platform/authorizations:
    post:
      summary: Create instruction
      description: >-
        Creates a purchase instruction (spending authorization) for the token's
        customer and returns a short-lived activation link that the user opens
        to approve it with a Passkey. Requires `portal:write`.
      operationId: createInstruction
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInstructionRequest'
            examples:
              existingCard:
                summary: Sign with an existing card
                value:
                  request_id: platform-ref-001
                  title: Office supplies budget
                  description: Monthly office supplies purchase
                  payment_instrument_id: pi_...
                  is_recurring: false
                  effective_until_time: '2026-12-31 23:59:59'
                  shipping_address:
                    name: Example User
                    line1: 1 Market Street
                    line2: Suite 100
                    line3: null
                    city: San Francisco
                    state: CA
                    zip: '94105'
                    country_code: US
                  mandates:
                    - description: Purchase office supplies
                      amount_limit: '100.00'
                      currency_code: USD
                      recurring_frequency: null
                      merchant_category_code: '5732'
                      preferred_merchant_name: null
                      effective_until_time: null
              bindAndSign:
                summary: Bind a card and sign
                value:
                  request_id: platform-ref-002
                  title: Office supplies budget
                  description: Monthly office supplies purchase
                  is_recurring: false
                  shipping_address:
                    name: Example User
                    line1: 1 Market Street
                    line2: Suite 100
                    line3: null
                    city: San Francisco
                    state: CA
                    zip: '94105'
                    country_code: US
                  mandates:
                    - description: Purchase office supplies
                      amount_limit: '100.00'
                      currency_code: USD
                      recurring_frequency: null
                      merchant_category_code: '5732'
                      preferred_merchant_name: null
                      effective_until_time: null
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    description: '`200` on success.'
                    example: 200
                  msg:
                    type: string
                    description: Result message.
                    example: Success
                  data:
                    $ref: '#/components/schemas/CreateInstructionResponse'
              examples:
                existingCard:
                  summary: Sign with an existing card
                  value:
                    code: 200
                    msg: Success
                    data:
                      instruction_id: inst_...
                      status: CREATED
                      payment_instrument_id: pi_...
                      activation_url: https://agent.clinkbill.dev/sign/ss_...
                      activation_expires_at: '2026-11-09T10:30:00Z'
                bindAndSign:
                  summary: Bind a card and sign
                  value:
                    code: 200
                    msg: Success
                    data:
                      instruction_id: inst_...
                      status: PENDING
                      activation_url: https://agent.clinkbill.dev/sign/ss_...
                      activation_expires_at: '2026-11-09T10:30:00Z'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing, expired, or invalid portal token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Wrong token audience, missing `portal:write` scope, or a platform
            client token used instead of a portal token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            `request_id` was reused with different parameters
            (`portal_conflict`, `code` `71211011`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    CreateInstructionRequest:
      type: object
      required:
        - request_id
        - title
        - mandates
      properties:
        request_id:
          type: string
          description: Platform-side reference and idempotency key, 8–128 characters.
          minLength: 8
          maxLength: 128
          example: platform-ref-001
        title:
          type: string
          description: Non-empty instruction title.
          minLength: 1
          example: Office supplies budget
        description:
          type: string
          description: Instruction description.
          example: Monthly office supplies purchase
        payment_instrument_id:
          type: string
          description: >-
            Existing usable payment instrument owned by the token's customer.
            Omit it to bind a new card and sign.
          example: pi_...
        is_recurring:
          type: boolean
          description: >-
            Whether the instruction contains recurring mandates. When `true`,
            every mandate must include `recurring_frequency`.
          example: false
        effective_until_time:
          type: string
          description: >-
            Last time the instruction can be used, in UTC `yyyy-MM-dd HH:mm:ss`.
            Ignored in bind-and-sign mode: Clink overrides it (and each
            mandate's `effective_until_time`) with now +
            `pendingActivationWindowMinutes` (7 days by default), so read the
            effective value from the instruction.
          example: '2026-12-31 23:59:59'
        shipping_address:
          $ref: '#/components/schemas/ShippingAddress'
        mandates:
          type: array
          description: One or more mandates.
          items:
            $ref: '#/components/schemas/MandateInput'
          minItems: 1
    CreateInstructionResponse:
      type: object
      properties:
        instruction_id:
          type: string
          description: Created instruction ID.
          example: inst_...
        status:
          type: string
          description: >-
            Instruction status: `CREATED` when signing with an existing card,
            `PENDING` when binding a new card.
          enum:
            - CREATED
            - PENDING
          example: CREATED
        payment_instrument_id:
          type: string
          description: >-
            Payment instrument the instruction uses. Absent or `null` in
            bind-and-sign mode, where no card is bound yet.
          example: pi_...
        activation_url:
          type: string
          description: >-
            Short-lived activation link the user opens to approve the
            instruction. In bind-and-sign mode, the page also collects the card
            before authorization, in the same Passkey ceremony. The link
            contains an opaque signing session ID, not a portal token, and can
            be exchanged for a normal Clink browser login session for that
            customer while it is valid. It supports repeated exchanges (for
            example, when the user refreshes the page) and stops working at
            `activation_expires_at` (30 minutes by default) or once the
            instruction becomes `ACTIVE` or final. Omitted when a retried
            `request_id` refers to an instruction that is already signed or
            final.
          example: https://agent.clinkbill.dev/sign/ss_...
        activation_expires_at:
          type: string
          description: >-
            Time after which the activation link no longer works. Omitted
            together with `activation_url`.
          format: date-time
          example: '2026-11-09T10:30:00Z'
    ErrorResponse:
      type: object
      description: Business errors use the standard envelope without `data`.
      properties:
        code:
          type: integer
          description: >-
            Numeric business error code. Judge an error by the HTTP status
            together with `code`, not by a string error code.
        msg:
          type: string
          description: Human-readable description.
    ShippingAddress:
      type: object
      description: Shipping address.
      properties:
        name:
          type: string
          description: Recipient name.
          example: Example User
        line1:
          type: string
          description: Address line 1.
          example: 1 Market Street
        line2:
          type: string
          description: Address line 2.
          example: Suite 100
        line3:
          type: string
          description: Address line 3.
        city:
          type: string
          description: City.
          example: San Francisco
        state:
          type: string
          description: State or province.
          example: CA
        zip:
          type: string
          description: Postal code.
          example: '94105'
        country_code:
          type: string
          description: Country code.
          example: US
    MandateInput:
      type: object
      required:
        - description
        - amount_limit
        - currency_code
      properties:
        description:
          type: string
          description: Non-empty purpose of the authorized spending.
          minLength: 1
          example: Purchase office supplies
        amount_limit:
          type: string
          description: >-
            Positive decimal string in major currency units, at most 18 integer
            digits and 2 decimal places. `"100.00"` means USD 100.00.
          example: '100.00'
        currency_code:
          type: string
          description: >-
            Three-letter currency code. All mandates in one instruction must use
            the same currency.
          example: USD
        recurring_frequency:
          type: string
          description: Required for every mandate when `is_recurring` is `true`.
          enum:
            - WEEKLY
            - MONTHLY
            - YEARLY
        merchant_category_code:
          type: string
          description: Merchant category restriction, when applicable.
          example: '5732'
        preferred_merchant_name:
          type: string
          description: Preferred merchant name.
        effective_until_time:
          type: string
          description: >-
            Mandate expiry, in UTC `yyyy-MM-dd HH:mm:ss`. In bind-and-sign mode,
            Clink overrides it together with the instruction expiry; read the
            effective value from the instruction.
  securitySchemes:
    PortalToken:
      type: http
      scheme: bearer
      description: >-
        Portal user token from `POST /agent/cwallet/platform/portal/tokens`.
        Reads require `portal:read`; writes require `portal:write`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.