Challenges

🚧
Beta testing phase
This is not the final version of the product, and is still subject to change.
If you are interested in early access to this feature, please contact [email protected]!

Challenge resource

Challenges are a mechanism for enabling access to endpoints protected by multi-factor authentication (MFA).

{
  "data": {
    "id": "cha_C5GkBJtCaF3HsMeMLz3dZDht",
    "type": "challenge",
    "attributes": {
      "action": "card.activate",
      "factor": "sms",
      "resource_id": "card_F4iHnHWrRU42kH2udcLw8H66",
      "created_at": "2025-07-04T06:33:52Z",
      "resend_at": "2025-07-04T06:34:52Z",
      "updated_at": "2025-07-04T06:33:52Z"
    }
  }
}

Parameter	Type	Description
action	string	Action restricted by MFA. See MFA actions below for more details.
factor	string	"email" or "sms"
resource_id	string	The id of the resource on which to execute the `action`.
created_at	timestamp	Date when the challenge was created.
resend_at	timestamp	Date when the OTP of the challenge can be resnt.
updated_at	timestamp	Date when the challenge was updated.

MFA actions

Action	Description
card.activate	`POST` /v1/issuing/card_programs/:card_program_id/cards/:card_id/activate
card.view_private	`GET` /v1/issuing/card_programs/:card_program_id/cards/:card_id?private=true

For Issuing API, the following endpoints require MFA via the challenge flow:

Retrieve a card (private set to true)
Activate a card

This flow is diagrammed below:

sequenceDiagram
    actor Client
    participant IssuingAPI as Issuing API

    Client->>IssuingAPI: POST /v1/issuing/challenges
    IssuingAPI-->>Client: challenge resource

    Client->>IssuingAPI: POST /v1/issuing/challenges/:challenge_id/verify
    IssuingAPI-->>Client: X-MFA-Token

Challenge creation

Call the POST /v1/issuing/challenges endpoint to create a challenge. A resource_id and action must be provided. resource_id is the id of the resource on which you want to perform an action protected by MFA. action is a string defining the action you want to perform on the resource provided.

If the call is successful, the owner of the resource will receive an OTP and a challenge resource will be returned to the client.

Challenge verification

Call the POST /v1/issuing/challenges/:challenge_id/verify endpoint. code will be the OTP sent to the owner of the resource. If the resource is a card, the OTP will be sent to either the registered email address or phone number of the cardholder.

If the code is correct, a 204 response will be returned and there will be an MFA token in the X-MFA-Token header. You can then use this token to call endpoints that require MFA by passing it as X-MFA-Token in the request headers.