Delegated API client integration

This guide walks through the authentication flow for a delegated API clientDelegated API client An 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.

info

Before following this guide, complete the pre-integration setup described in the Delegation of AuthorityDelegation of Authority A program option that lets your backend perform automated operations on behalf of identity users without the user being present or completing a step-up. The delegated API client authenticates over mutual TLS (mTLS) and obtains an access token scoped to a specific identity, removing the need for SCA on its calls. End users grant consent once during onboarding. See the [Delegation of Authority overview](/apis/authentication/delegation-overview/) for the full flow. 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:

GET/identitiesTry it

Response

{
  "identities": [
    {
      "id": {
        "type": "CONSUMER",
        "id": "string"
      },
      "name": "string"
    }
  ],
  "count": 0,
  "responseCount": 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 client An 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 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.

caution

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.

POST/access_tokenTry it

Request

{
  "identity": {
    "type": "CONSUMER",
    "id": "string"
  },
  "clientAssertion": "string"
}

Response

{
  "token": "string",
  "identity": {
    "type": "CONSUMER",
    "id": "string"
  },
  "credentials": {
    "type": "ROOT",
    "id": "string"
  },
  "status": "STANDARD"
}

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.

info

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 cards

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 accounts

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 transfers

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

info

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 clientDelegated API client An 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 - 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 AuthorityDelegation of Authority A program option that lets your backend perform automated operations on behalf of identity users without the user being present or completing a step-up. The delegated API client authenticates over mutual TLS (mTLS) and obtains an access token scoped to a specific identity, removing the need for SCA on its calls. End users grant consent once during onboarding. See the [Delegation of Authority overview](/apis/authentication/delegation-overview/) for the full flow. 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 - 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 for corporate identities. Contact your account manager for the equivalent behaviour in consumer (KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers.) flows if 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. supports consumer identities.

The consent is collected once during onboarding and does not need to be renewed for each delegated operation.