Get an access token

When you create or interact with your customers' financial instrumentsInstrumentA financial product owned by a customer. There are two types: Managed Accounts (stored-value accounts that hold balances and can receive wire transfers) and Managed Cards (prepaid cards - virtual or physical - used for purchases)., you act on their behalf. Every such API request must include an identity-scoped Access Token. You present this token in the request's Authorization header so Weavr can authenticate the request as the user acting through your app - a root userRoot userThe individual who creates the customer. For corporates, the root user needs to be a legal representative of the company, such as a director or someone with power of attorney. For consumers, the root user is the customer. Every customer must always have one root user. or an authorised user of a corporate or consumer identity.

Before making these requests, verify the user with their Weavr credentials to obtain an Access Token. A consumer user always acts for their own identity. A corporate user has one set of credentials and can act for one or more corporate identities, so user verification has two possible outcomes.

Build every corporate integration to handle both login outcomes, even if each of your users belongs to one corporate today. This avoids changing your authentication architecture when a user gains access to another corporate.

Token lifetime: 5 minutes from last activity

End-user tokens expire after 5 minutes of inactivity. There is no refresh endpoint. To continue after expiry, the user must log in again using POST/login_with_password. Plan your UX around user activity rather than waiting for a 401 response. For example, prompt the user to take an action when less than 1 minute remains on the session.

Verify the user and get an Access Token

User verification checks the user's credentials. Its goal is to obtain an Access Token for the user and the identity they will act for. Once you have that token, use it to authenticate the user's API requests.

1. Verify the user
2. Select an identity
3. Authenticate API requests with the Access Token

1. Verify the user

Verify the user with their Weavr credentials:

POST/login_with_passwordOpen API reference →

/login_with_password

{  "email": "[email protected]",  "password": {    "value": "Passw0rd!"  }}

Inspect tokenType in the response before using the token:

tokenType	Meaning	Next step
ACCESS	The user has one active identity, which Weavr selected automatically.	Use the returned Access Token to authenticate identity-scoped API requests.
AUTH	The user has more than one active identity. The token identifies the user but does not select an identity.	Retrieve the user's identities, then exchange the Auth Token for an Access Token.

The response also includes identity when tokenType is ACCESS. It is omitted when tokenType is AUTH.

2. Associate with an identity (when required)

Skip this step for single-identity users

If your user only has access to one identity, then you can skip this step.

Get a list of the user's identities

When login returns tokenType: AUTH, use that token to retrieve the identities available to the user:

GET/identitiesOpen API reference →

/identities

Present the identities in your app and let the user select the customer they want to act for. If your app already has an unambiguous customer context, you can select the matching identity without showing a picker.

Request the access token

Exchange the Auth Token for an Access Token, specifying the selected identity:

POST/access_tokenOpen API reference →

/access_token

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

The resulting Access Token is scoped to that identity. It also carries the user's type (ROOT or USER) and roles on that identity, which can differ from their type and roles elsewhere. Its status is STANDARD or STEPPED_UP.

Don't assume login returns an Access Token

A user who receives an Access Token today can receive an Auth Token after they are linked to a second identity. Always branch on tokenType, rather than treating multiMultiWeavr Multi is an embedded finance solution that allows you to integrate financial services into your own application, providing a seamless experience for your customers. It enables you to offer managed accounts, managed cards, and transactions without requiring financial expertise.-identity access as a separate integration mode.

3. Authenticate API requests with the Access Token

Pass the identity-scoped Access Token with every API request that acts on the user's behalf:

Authorization: Bearer ACCESS_TOKEN

Some API descriptions and SDK methods call this value an auth_token for backward compatibility. In these cases, pass the Access Token, not an Auth Token.

---

Switch identities

To switch identity without asking the user to enter their credentials again:

1. Call GET /identities with the current Access Token if you need to refresh the available identities.
2. Call POST /access_token with the current Access Token and the new identity.
3. Replace the old Access Token with the token returned in the response.

The old Access Token becomes invalid as soon as the exchange succeeds. A switch replaces the token within that session rather than adding a second one. Separate logins remain independent sessions, so a switch in one does not affect another. Account for this in multiMultiWeavr Multi is an embedded finance solution that allows you to integrate financial services into your own application, providing a seamless experience for your customers. It enables you to offer managed accounts, managed cards, and transactions without requiring financial expertise.-tab apps, where every tab must pick up the new token.

Exchanging an Auth Token does not invalidate it. If an exchange fails, for example because the user selected an identity they are no longer linked to, you can retry with the same Auth Token.

If the current Access Token is stepped up, the new token remains stepped up. The user does not need to repeat the second factor solely because they switched identities. If the user's roles on an identity change while they are signed in, exchange again to pick up the new permissions.

---

End the session

When the user signs out of your app, invalidate their token explicitly rather than letting it expire:

POST/logoutOpen API reference →

/logout

Logout terminates the session identified by the Access Token in the Authorization header. The token becomes invalid immediately, and the user must log in again to get a new one. Discard the token from your app's storage at the same time.

Explicit logout matters even with the short token lifetime: it closes the session immediately instead of leaving up to 5 minutes in which the token could still be used.

---

Biometrics

For implementation guidance, see the biometrics SDKs for iOS, Android, and React Native.

Enrollment via biometrics

Tokens are used as follows:

1. Call POST /login_with_password and inspect tokenType.
2. If it is AUTH, select an identity and exchange the token. If it is ACCESS, use the returned token directly.
3. Use the Access Token to enroll a user device for authentication using push notifications.
4. A push notification is sent to the user. Once they provide consent through the embedded SDK, the active Access Token is stepped up.

Login via biometrics

Tokens are used as follows:

1. Initiate the login via biometrics screen through the SDK. The end user completes the login.

2. The token delivered by webhook is an Auth Token, usable only against the following endpoints:

   GET/identitiesOpen API reference →

   /identities
   POST/access_tokenOpen API reference →

   /access_token

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

3. Select an identity and exchange the Auth Token for an Access Token. The returned Access Token is already stepped up.