Delegated API client integration
This guide walks through the authentication flow for a delegated API clientDelegated API clientAn API client type used with [Delegation of Authority](/apis/authentication/delegation-overview/) that authenticates via mutual TLS instead of end-user credentials. It receives access tokens scoped to a specific identity user and can perform operations server-to-server without triggering Strong Customer Authentication step-up., 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 program using the following endpoint:
/identities /identities{ "offset": 0, "limit": 0}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 clientDelegated API clientAn API client type used with [Delegation of Authority](/apis/authentication/delegation-overview/) that authenticates via mutual TLS instead of end-user credentials. It receives access tokens scoped to a specific identity user and can perform operations server-to-server without triggering Strong Customer Authentication step-up. ID, obtained from the Embedder PortalEmbedder PortalA 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 our token endpoint to receive a delegated access token. The request must be made over mTLS using your registered certificate.
/access_token /access_token{ "identity": { "type": "CONSUMER", "id": "123456789" }, "clientAssertion": "string", "token": "string"}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.
Delegated access tokens have a limited lifetime-the expiry is returned in the token response. When a token expires, generate a new client assertion and call this endpoint again to obtain a fresh token; there is no refresh endpoint. Cache the token in your backend and re-request before it expires to avoid unnecessary calls.
The delegated access token is pre-authorized-no SCASCA (Strong Customer Authentication). 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 cards
| Endpoint | Description | Notes |
|---|---|---|
POST /managed_cards | Create a managed cardManaged CardA 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 OwnerThe 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 CardA 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 CardA 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 CardA 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 CardA 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 accounts
| Endpoint | Description | Notes |
|---|---|---|
POST /managed_accounts | Create a managed accountManaged AccountAn 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 AccountAn 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 transfers
| Endpoint | Description | Notes |
|---|---|---|
POST /outgoing_wire_transfers | Create an outgoing wire transferWire TransferA 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 TransferA 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). 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). 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 clientDelegated API clientAn API client type used with [Delegation of Authority](/apis/authentication/delegation-overview/) that authenticates via mutual TLS instead of end-user credentials. It receives access tokens scoped to a specific identity user and can perform operations server-to-server without triggering Strong Customer Authentication step-up. operations are not gated by SCASCA (Strong Customer Authentication). 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 OperationsThe 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 turned on for your program, end users see an additional consent screen during onboarding. The screen informs the user that your platform may perform certain financial operations on their behalf.
The consent screen appears during corporate (KYBKYB (Know Your Business). Know Your Business - the identity verification process for corporate customers. This process allows you to securely verify your business customer's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers.) onboarding for corporatesCorporates (Corporate Identity). Business entities that can be onboarded as customers on Weavr. Corporate customers represent companies and require Know Your Business (KYB) verification. They can have multiple authorised users and issue cards to card assignees.. Contact your account manager for the equivalent behaviour in consumer (KYCKYC (Know Your Customer). Know Your Customer - the identity verification process for consumer customers. This process allows you to securely verify your user's identity. Weavr asks users to submit the information and documentation they need for approval by financial providers.) flows if your programmeProgrammeA programme represents your application within Weavr. Everything you create - customers, instruments, and transactions - sits beneath a programme. When you register as an Embedder, you receive a programme in the Sandbox and, once approved, one in Production. supports consumersConsumers (Consumer). Individual people who can be onboarded as customers on Weavr. Consumer customers require Know Your Customer (KYC) verification. For consumers, the card owner and card assignee are typically the same person..
The consent is collected once during onboarding and does not need to be renewed for each delegated operation.