Delegation of authority

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. (DoA) enables your backend systems to perform automated operations on behalf of identity users without requiring the user to be present or to complete a step-up authentication challenge.

This is useful for scenarios where your platform needs to execute financial operations programmatically, such as automated card creation, scheduled transfers, or 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. triggered by business logic in your backend.

info

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 available for automation use cases only. The 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. acts on behalf of an identity user through your backend system.

How it works

We support two types of API clients, each designed for different interaction patterns:

User API client

The standard API client used in the existing Weavr API integration. End users authenticate directly using their credentials, and operations are performed in the context of their active session. This client type requires Strong Customer Authentication (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 for sensitive operations.

Delegated API client

A new client type that allows your backend system to perform operations on behalf of identity users. Instead of the user authenticating directly, your backend authenticates using a certificate-based mechanism and receives a delegated access token scoped to a specific identity.

Operating modes

User mode

The standard mode where end users interact with your app directly. The user logs in, completes 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 when required, and performs operations through your frontend. This is the existing Weavr API authentication flow.

Delegated system mode

Your backend system authenticates as 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. and obtains tokens scoped to specific identity users. Operations are executed server-to-server without requiring the user to be present. 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 not required for operations performed via a delegated access token.

Architecture overview

The delegated system mode flow works as follows:

1. Your backend generates a signed client assertion (JWT) that identifies the target identity user.
2. Your backend sends the client assertion to our token endpoint, authenticating via mutual TLS (mTLS).
3. We validate the assertion, verify the certificate, and issue a delegated access token scoped to the specified identity.
4. Your backend uses the delegated access token to call Weavr API endpoints on behalf of that identity user.

Pre-integration setup

Before integrating with the 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., complete the following setup steps with Weavr:

IP allowlisting

Provide Weavr with the static IP addresses of the backend servers that make delegated API calls. Only requests from allow-listed IPs are accepted for 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. Requests from a non-allow-listed IP are rejected with an HTTP 403 Forbidden response-check the source IP of the request if you see this error during integration.

Certificate exchange

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. uses mutual TLS (mTLS) for authentication. You need to:

1. Generate an RSA key pair (minimum 2048-bit).
2. Share the public key with Weavr during onboarding. We register it against 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..
3. Store the private key securely on your backend servers. This key is used to sign client assertions (JWTs) when requesting delegated access tokens.

caution

Never expose your private key. It must remain securely stored on your backend servers and must not be shared with Weavr or any third party.

Manage API clients

You can create and manage delegated API clientsDelegated 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. through 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..

Create a delegated API client

1. Navigate to the API clients section in 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..
2. Select Create API client and choose the Delegated client type.
3. Provide the required configuration, including the public key for mTLS authentication.
4. Save the client. Note the client_id-your backend needs this when generating client assertions.

View and edit API clients

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. displays all configured API clients with their type (User or Delegated), status, and creation date. You can update the configuration of 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., including rotating the public key, from the portal.

End-user consent

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 are presented with a 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 process. This informs them that your platform may perform certain operations on their behalf. The consent is collected once during onboarding and covers all delegated operations.

Next steps

See Delegated API client integration for the step-by-step guide to authenticating and making API calls with 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..