Authorised API client

An Authorised API client lets your backend call the Weavr API on your own corporate identity, without a user signing in. Use it to automate your own operations, such as managing your cards and accounts, running bulk updates, and reading statements.

Intended use

An Authorised API client operates only on your embedder corporate: your own business on your programme. You can't use it to act on behalf of your customers. To automate operations for customers who have given consent, use a Delegated API client instead.

Allowed operations

The operations your Authorised API client can perform are agreed case by case with our support team, based on what your integration needs. Contact support to begin the process. Calls outside that set return 403 INSUFFICIENT_PERMISSIONS.

Some operations should stay with a user

Operations that need a person present are normally kept on user authentication, so the user can complete strong customer authentication (SCA). Typical examples are confirming outgoing wire transfers, adding beneficiaries, and showing card details in clear through the Secure UI components. If agreed, your backend can still retrieve card details in tokenized form.

Enabling an Authorised API client doesn't change user authentication. Users can keep signing in as before, so you can move your backend calls across gradually.

How it differs from other API clients

All three client types call the same Weavr API. They differ in who they act for, how they authenticate, and who decides what they can do.

	User API client	Delegated API client	Authorised API client
Acts for	The signed-in user	Your customers' identities, with their consent	Your own corporate identity only
How it authenticates	User credentials (password, biometrics), then `POST /access_token`	Client assertion signed with your private key, then `POST /access_token`	Client assertion signed with your private key, then `POST /access_token`
SCA step-up	Required where the endpoint asks for it	Not required on supported endpoints	Not required
Operations allowed	The user's role	The endpoints listed for delegation	A set agreed with our support team for your integration
Who sets it up	You, in the Embedder Portal	You, once Weavr has enabled delegation for your programme	Our support team, with you
Customers who can use it	Whoever signs in	Customers who consented during onboarding	Corporates Weavr has authorized on your programme

Which client type do you need?

If your backend works on your own business's cards and accounts, use an Authorised API client. If it works on your customers' cards and accounts, use a Delegated API client. If a person is present and signs in, use a User API client.

Set up an Authorised API client

Contact our support team to start. Set-up is done together, separately for Sandbox and Live, and for each programme you want to automate.

Agree the operations. Tell support which operations your backend needs. Support agrees the set with you and configures it.
Weavr enables the client. Support enables Authorised API client mode on your programme, authorizes your corporate identity on it, and creates the API client.
Find your credentials. In the Embedder Portal, open Developers > API credentials > API clients for the programme. Note the API client ID and the programme's API key. Only the root user can see these details, so the root user must sign in to the portal to retrieve them.
Generate and upload a certificate. See Generate and upload a certificate.
Test in Sandbox. Request a token and call one agreed endpoint before moving to Live.

Everything is per programme

An API client, its certificate, the API key, and the authorized corporate all belong to one programme. A token request must use all four from the same programme, or it's refused. If you have several programmes, repeat the set-up for each.

You need	Where to find it
API client ID	Embedder Portal > API clients
API key	Embedder Portal, for the same programme as the API client
Corporate identity ID	Your corporate's ID, as authorized by Weavr on that programme
Private key and certificate	You generate them, as described in the following section

Generate and upload a certificate

Weavr checks your client assertion against an X.509 certificate that you upload for the API client. You keep the matching private key and sign with it. The certificate is safe to share; the private key never leaves your systems.

Upload a certificate, not a public key

The upload needs a file that starts with -----BEGIN CERTIFICATE-----. A public key (-----BEGIN PUBLIC KEY-----) is rejected, as are a private key, a certificate chain, and a non-RSA key.

Certificate requirements

Requirement	Value
Format	X.509 certificate, PEM encoded (Base64 text between the `BEGIN CERTIFICATE` and `END CERTIFICATE` lines)
Key type	RSA, 2048 bits or more. EC keys aren't supported
Contents	One certificate. Not a chain, bundle, or key file
Validity	Must have an expiry date. Assertions fail once it has expired
Filename	Any. `.crt` and `.pem` both work; Weavr reads the content, not the extension
Certificates per API client	Up to 5 active
Self-signed	Accepted. A CA-issued certificate isn't required

1. Generate a key pair and certificate

openssl req -x509 -newkey rsa:2048 -sha256 -nodes \
  -keyout private-key.pem \
  -out certificate.pem \
  -days 365 \
  -subj "/CN=${YOUR_COMPANY}-weavr-api-client"

This creates two files:

certificate.pem: upload this to Weavr.
private-key.pem: keep it secret and use it to sign client assertions. Never upload or share it.

To reuse a key you already have, create a certificate from it:

openssl req -x509 -key private-key.pem -sha256 -days 365 \
  -subj "/CN=${YOUR_COMPANY}-weavr-api-client" \
  -out certificate.pem

2. Check the files before uploading

# Must print one certificate with "Public Key Algorithm: rsaEncryption" and a "Not After" date
openssl x509 -in certificate.pem -noout -text

# The two values must match: the private key belongs to this certificate
openssl x509 -in certificate.pem -noout -modulus | openssl sha256
openssl rsa  -in private-key.pem  -noout -modulus | openssl sha256

If the first command fails with unable to load certificate, the file isn't a certificate. You may have exported the public key instead.

3. Upload the certificate

In the Embedder Portal, open API clients, select the API client, and upload certificate.pem. Upload the whole file, including the BEGIN and END lines. You need the API client management permission, and the portal may ask you to confirm with a one-time code from your authenticator app.

Rotate a certificate

Weavr accepts an assertion signed by the private key of any active certificate on the API client, so you can rotate without downtime:

Generate a new key pair and certificate.
Upload the new certificate. Both are now active.
Switch your backend to sign with the new private key.
Delete the old certificate in the Embedder Portal.

Set a reminder well before the expiry date. After expiry, token requests fail with Invalid assertion - no matching certificate registered.

Build the client assertion

The client assertion is a short-lived JWT that proves the request comes from your API client. Create a new one for every token request.

sub is your API client ID

Put your API client ID in sub, as a string. The identity you want to act as goes in the request body, not in the JWT.

Part	Field	Value
Header	`alg`	`RS256` (`RS384`, `RS512`, and `PS256` to `PS512` also work)
Header	`typ`	`JWT`
Payload	`sub`	Your API client ID, as a JSON string, for example `"${API_CLIENT_ID}"`. Required
Payload	`iss`	Your API client ID again. Recommended
Payload	`iat`	Current time, Unix seconds
Payload	`exp`	`iat` + 300 or less (5 minutes)
Signature		Signed with the private key whose certificate you uploaded to this API client

// Header
{ "alg": "RS256", "typ": "JWT" }

// Payload
{
  "sub": "${API_CLIENT_ID}",
  "iss": "${API_CLIENT_ID}",
  "iat": 1793715390,
  "exp": 1793715690
}

Keep IDs as strings

Weavr IDs are longer than JavaScript can hold exactly as numbers. Send sub as a string; as a number it can lose its last digits and no longer match your API client.

Node.js (jose)

import { readFileSync } from "node:fs";
import { importPKCS8, SignJWT } from "jose";

const apiClientId = process.env.WEAVR_API_CLIENT_ID; // string
const privateKey = await importPKCS8(
  readFileSync("private-key.pem", "utf8"),
  "RS256",
);

const clientAssertion = await new SignJWT({})
  .setProtectedHeader({ alg: "RS256", typ: "JWT" })
  .setSubject(apiClientId)
  .setIssuer(apiClientId)
  .setIssuedAt()
  .setExpirationTime("5m")
  .sign(privateKey);

importPKCS8 needs a key starting with -----BEGIN PRIVATE KEY-----, which is what the preceding openssl req command produces. For an older -----BEGIN RSA PRIVATE KEY----- file, convert it first:

openssl pkcs8 -topk8 -nocrypt -in old-key.pem -out private-key.pem

Python (PyJWT)

import os, time
import jwt  # pip install "pyjwt[crypto]"

api_client_id = os.environ["WEAVR_API_CLIENT_ID"]  # string
with open("private-key.pem", "rb") as f:
    private_key = f.read()

now = int(time.time())
client_assertion = jwt.encode(
    {"sub": api_client_id, "iss": api_client_id, "iat": now, "exp": now + 300},
    private_key,
    algorithm="RS256",
    headers={"typ": "JWT"},
)

To inspect an assertion while debugging, decode its header and payload only, for example with jwt.decode(token, options={"verify_signature": False}). Never paste a full signed assertion or your private key into a support ticket or an online tool.

Get an access token and call the API

Exchange the client assertion for an access token scoped to your corporate identity, then call the API with it.

1. Request an access token

Call POST/access_token with the client assertion and your corporate identity:

POST https://sandbox.weavr.io/multi/access_token
api-key: ${YOUR_API_KEY}
Content-Type: application/json

{
  "identity": {
    "type": "CORPORATE",
    "id": "${CORPORATE_ID}"
  },
  "clientAssertion": "${CLIENT_ASSERTION}"
}

Field	Value
`api-key` header	The API key of the same programme as the API client
`identity.type`	Always `CORPORATE`
`identity.id`	Your corporate identity ID, as authorized by Weavr on that programme
`clientAssertion`	The signed JWT from the previous step

The response contains the access token in token. See POST/access_token for the full schema.

2. Call the API

GET https://sandbox.weavr.io/multi/managed_cards
api-key: ${YOUR_API_KEY}
Authorization: Bearer ${ACCESS_TOKEN}

The token acts as your corporate identity, within the operations agreed with Weavr. Agreed endpoints don't ask for an SCA step-up.

Token lifetime

There is no refresh endpoint. When a token expires, create a new client assertion and request a new token. Cache the token and reuse it while it's valid, rather than requesting one per call.

Errors and troubleshooting

Most failures come from a file that isn't a certificate, or from IDs that belong to different programmes.

Certificate upload

Response	Cause	Fix
`409 INVALID_CERTIFICATE`	The file isn't a single, complete X.509 certificate with an RSA key: a public key, private key, chain, truncated file, or EC key	Run the `openssl x509` check and upload `certificate.pem` whole
`409 CERTIFICATE_NO_EXPIRY_DATE`	The certificate has no expiry date	Generate it with `-days` set
`409 LIMIT_EXCEEDED`	The API client already has 5 active certificates	Delete one you no longer use
`403`	Certificate management isn't enabled for your account, or you lack the API client management permission	Contact our support team

Token request

These errors come from POST/access_token.

Response	Cause	Fix
`400 Invalid assertion. Expected a valid JWT`	`clientAssertion` isn't a well-formed signed JWT	Check the JWT has three Base64URL parts and the claims described in this guide
`400 Invalid assertion subject`	`sub` isn't an API client ID, for example it holds an identity ID or a name	Put your API client ID in `sub`
`400 Invalid assertion - no matching certificate registered`	No active certificate on that API client verifies the signature: no certificate uploaded to this client, signed with a different private key, unsupported `alg`, or the certificate has expired	Upload the certificate to this client, compare the moduli, and sign with `RS256`
`403 INSUFFICIENT_PERMISSIONS`	The assertion is valid, but the request doesn't line up: the API key, API client, and corporate are from different programmes; `identity.type` isn't `CORPORATE`; or the corporate isn't authorized on the programme	Use the API key and corporate of the programme the API client belongs to

Calling the API

Response	Cause	Fix
`401`	Token missing or expired	Request a new token
`403 INSUFFICIENT_PERMISSIONS`	The operation isn't in the set agreed for your API client	Contact our support team to add it

How it differs from other API clients​

Set up an Authorised API client​

Generate and upload a certificate​

Certificate requirements​

1. Generate a key pair and certificate​

2. Check the files before uploading​

3. Upload the certificate​

Rotate a certificate​

Build the client assertion​

Node.js (jose)​

Python (PyJWT)​

Get an access token and call the API​

1. Request an access token​

2. Call the API​

Token lifetime​

Errors and troubleshooting​

Certificate upload​

Token request​

Calling the API​