Delegated API client integration
This guide walks through the authentication flow for a delegated API client, from retrieving identity IDs to executing operations with a delegated access token.
Before following this guide, complete the pre-integration setup described in the Delegation of Authority overview.
Authentication flow
1. Retrieve identity IDs
Your backend needs the identity ID of the user on whose behalf it will operate. You can retrieve the list of identities associated with your programmeProgramme A programme represents your application within Weavr. Everything you create — Identities, Instruments, Transactions — sits beneath a Programme. When you register as an Embedder, you receive a Programme in the Sandbox and, once approved, one in Production. using the following endpoint:
Store the identity IDs in your backend system. You will use these when generating client assertions.
2. Generate a client assertion
Create a signed JWT (JSON Web Token) that serves as your client assertion. This JWT tells Weavr which identity user your backend wants to act on behalf of.
The JWT must be signed using the RS256 algorithm with the private key that corresponds to the public key registered with Weavr during setup.
JWT header
{
"alg": "RS256",
"typ": "JWT"
}
JWT payload
{
"sub": "${IDENTITY_ID}",
"iss": "${CLIENT_ID}",
"iat": 1700000000,
"exp": 1700000300,
"jti": "unique-request-id-12345"
}
| Field | Description |
|---|---|
sub | The identity ID of the user on whose behalf the operation is performed. |
iss | Your delegated API client ID, obtained from the Embedder PortalEmbedder Portal A web-based portal where embedders can access their Weavr account, manage API credentials, configure settings, view dashboards, and access documentation. The portal provides access to both sandbox and production environments, with separate credentials for each.. |
iat | Issued-at timestamp (Unix epoch in seconds). |
exp | Expiration timestamp (Unix epoch in seconds). Keep the validity window short, for example 5 minutes. |
jti | A unique identifier for this assertion. Use a UUID or similar unique value to prevent replay attacks. |
Keep the JWT validity window as short as practical. A window of 5 minutes or less is recommended. Each jti value must be unique across requests.
3. Obtain a delegated access token
Send the client assertion to Weavr's token endpoint to receive a delegated access token. The request must be made over mTLS using your registered certificate.
Include the client assertion in the request body. The response contains a delegated access token scoped to the identity specified in the sub claim of your JWT.
The delegated access token is pre-authorized — no SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). step-up is required. Operations performed with this token bypass the standard step-up authentication flow.
4. Execute operations
Use the delegated access token in the Authorization header of your API requests, just as you would with a standard user access token. Include your API key in the api-key header as usual.
Authorization: Bearer ${DELEGATED_ACCESS_TOKEN}
api-key: ${YOUR_API_KEY}
Available operations
The following endpoints are accessible using a delegated access token. Some endpoints have specific requirements when called via delegation — check the notes column for details.
Managed cardsManaged Card A payment card (virtual or physical) that can be created and managed through the Weavr platform. Cards can operate in prepaid mode (with their own balance) or debit mode (linked to a managed account). All cards must be assigned to a card assignee who is an Authorised User.
| Endpoint | Description | Notes |
|---|---|---|
POST /managed_cards | Create a managed cardManaged Card A payment card (virtual or physical) that can be created and managed through the Weavr platform. Cards can operate in prepaid mode (with their own balance) or debit mode (linked to a managed account). All cards must be assigned to a card assignee who is an Authorised User. | userId is required in the request body to specify the card ownerCard Owner The individual or business entity that owns the cards and the funds available to be spent via card purchases. Before cards can be issued, the card owner must be onboarded on Weavr, including completing a KYB process for business card owners or a KYC process for individual card owners.. |
GET /managed_cards | List managed cardsManaged Card A payment card (virtual or physical) that can be created and managed through the Weavr platform. Cards can operate in prepaid mode (with their own balance) or debit mode (linked to a managed account). All cards must be assigned to a card assignee who is an Authorised User. | |
GET /managed_cards/${ID} | Get card details | |
PATCH /managed_cards/${ID} | Update a managed cardManaged Card A payment card (virtual or physical) that can be created and managed through the Weavr platform. Cards can operate in prepaid mode (with their own balance) or debit mode (linked to a managed account). All cards must be assigned to a card assignee who is an Authorised User. | |
POST /managed_cards/${ID}/block | Block a card | |
POST /managed_cards/${ID}/unblock | Unblock a card | |
DELETE /managed_cards/${ID}/destroy | Destroy a card | |
POST /managed_cards/${ID}/physical | Upgrade to physical cardPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. | |
POST /managed_cards/${ID}/physical/activate | Activate physical cardPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. |
Managed accountsManaged Account An account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr.
| Endpoint | Description | Notes |
|---|---|---|
POST /managed_accounts | Create a managed accountManaged Account An account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr. | |
GET /managed_accounts | List managed accountsManaged Account An account held at a financial institution that can be created and managed through the Weavr platform. Each account has a balance where customers can hold funds. Optionally, an IBAN can be assigned to enable wire transfers to bank accounts outside of Weavr. | |
GET /managed_accounts/${ID} | Get account details | |
GET /managed_accounts/${ID}/statement | Get account statement |
Transfers
| Endpoint | Description | Notes |
|---|---|---|
POST /transfers | Create a transfer | |
GET /transfers | List transfers | |
GET /transfers/${ID} | Get transfer details |
Sends
| Endpoint | Description | Notes |
|---|---|---|
POST /sends | Create a send | |
GET /sends | List sends | |
GET /sends/${ID} | Get send details |
Outgoing wire transfersWire Transfer A transaction that moves funds between accounts. An incoming wire transfer moves funds from a third-party bank account to a Weavr managed account, while an outgoing wire transfer moves funds from a Weavr managed account to a third-party bank account. Wire transfers require the managed account to have an assigned IBAN (for EUR) or sort code and account number (for GBP).
| Endpoint | Description | Notes |
|---|---|---|
POST /outgoing_wire_transfers | Create an outgoing wire transferWire Transfer A transaction that moves funds between accounts. An incoming wire transfer moves funds from a third-party bank account to a Weavr managed account, while an outgoing wire transfer moves funds from a Weavr managed account to a third-party bank account. Wire transfers require the managed account to have an assigned IBAN (for EUR) or sort code and account number (for GBP). | |
GET /outgoing_wire_transfers | List outgoing wire transfersWire Transfer A transaction that moves funds between accounts. An incoming wire transfer moves funds from a third-party bank account to a Weavr managed account, while an outgoing wire transfer moves funds from a Weavr managed account to a third-party bank account. Wire transfers require the managed account to have an assigned IBAN (for EUR) or sort code and account number (for GBP). | |
GET /outgoing_wire_transfers/${ID} | Get OWTOWT Outgoing Wire Transfer - a transaction that moves funds from a Weavr managed account to a bank account held at a third-party financial institution. OWTs require the managed account to have an assigned IBAN and the user to complete Strong Customer Authentication. details |
Transactions initiated via a delegated access token are not subject to SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). challenges. They proceed directly to execution without requiring user confirmation.
Rate limiting
Since delegated API client operations are not gated by SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics). challenges, there is no natural throttle on the rate of requests. To avoid performance degradation:
- Implement rate limiting in your backend to control the volume of delegated API calls.
- Space out bulk operationsBulk Operations The capability of grouping multiple individual API-based actions into a batch. Bulk operations allow you to execute hundreds or thousands of operations by making only one or two API calls, increasing throughput, accomplishing actions in a secure session, and reducing complexity in your application. rather than sending large bursts of requests simultaneously.
- Monitor API response times and back off if you observe increased latency or error rates.
Refer to Rate limiting for the general rate limit policies that apply to all API clients.
End-user experience changes
When Delegation of Authority is enabled for your programmeProgramme A programme represents your application within Weavr. Everything you create — Identities, Instruments, Transactions — sits beneath a Programme. When you register as an Embedder, you receive a Programme in the Sandbox and, once approved, one in Production., end users see an additional consent screen during the KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. onboarding flow. This screen informs the user that your platform may perform certain financial operations on their behalf.
The consent is collected once during onboarding and does not need to be renewed for each delegated operation.