User roles

Overview

Most users within a corporate identity interact with your service for a specific, everyday purpose — such as making purchases on an assigned card, or initiating payments. Beyond these end users, corporatesCorporates Business entities that can be onboarded as identities on Weavr. Corporate identities represent companies and require Know Your Business (KYB) verification. They can have multiple authorised users and issue cards to card assignees. also typically have staff who perform support and administrative functions, such as overseeing financial instruments, or controlling fund flows across the organisation, or managing users.

Weavr recommends following the principle of least privilege: each user should only be able to access and operate on the financial instruments and data that are relevant to their specific function. For example, a user should not be able to view or detokenise cards that belong to their colleagues, and a junior employee should not have access to account balances or the ability to initiate transfers.

To support this, Weavr provides a set of pre-configured roles that can be assigned to users individually or in combination to achieve the appropriate access level for their function. The available roles are:

Role	Description
Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	For users who need to access and spend on their own linked card(s) only. Permissions include viewing full card details, statements, managing their PIN, reporting lost/stolen cards, and performing actions related to their physical cardsPhysical 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. — but only for cards assigned to them.
Cards Management Role	For users responsible for managing a card programme at the identity. Permissions cover the management of all cards for an identity, including creating, blocking, unblocking cards, and managing spend rules. Access to sensitive card details (card number, CVV) is only allowed for cards that are assigned to them.
Funds Management Role	For users who need to manage fund inflows or outflows at the identity. Permissions allow access to financial instruments and transactions (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., transfers, sends, beneficiaries).
Access Management Role	For users responsible for creating and managing users. Permissions also allow for identity administration.
Admin	A role that combines all of the preceding roles and permissions. Has full access to all operations, including sensitive operations. This is the only role that can access sensitive card details for all cards of an identity.

Access to own cards

Users with roles Cards Management Role, Funds Management Role, and Access Management Role can also be linked to a card. They will have the same permissions as a Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users. over their own cards. Admin users have full permissions over all cards.

Combining roles

Multiple roles can be assigned to a single user, allowing flexible but controlled combinations of access. For example, a user could have both the Cards Management Role and Funds Management Role. The Admin role is designed to be used independently and is not intended to be combined with other roles.

Optional feature

Role-based access control is an optional feature. If you prefer to manage access restrictions within your own system, users can still be granted full (unrestricted) access via the Admin role. This may be appropriate where you, as the embedderEmbedder A company or developer that integrates Weavr's embedded finance services into their own application to provide financial services to their end customers., already enforce access controls at the app layer.

The following sections provide detailed information about user roles, including how to assign roles to users, and the exact permissions for each role.

Assigning roles to users

Roles are assigned when creating a user via POST /users and can be updated via PATCH /users/{user_id}.

Creating a user with roles

When creating an Authorised User, specify the roles in the request:

POST /users
{
  "name": "John",
  "surname": "Smith",
  "email": "john.smith@example.com",
  "mobile": {
    "countryCode": "44",
    "number": "7700900000"
  },
  "dateOfBirth": {
    "year": 1990,
    "month": 1,
    "day": 15
  },
  "roles": ["CARD_ASSIGNEE"]
}

roles is an optional field in the POST /users request. If no role is specified in the request, the default role of CARD_ASSIGNEE will be assigned.

Updating user roles

Roles can be updated via PATCH /users/{user_id}. Note that:

• Only users with the Access Management or Admin role can create or update users, including updating their roles.
• Users cannot modify their own roles.
• The Admin role cannot be removed from a Root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user..
• When updating roles via the patch, the field uses overwrite behaviour. Roles included in the list will be assigned, and roles not included will be unassigned.

PATCH /users/{id}
{
  "roles": ["CARD_ASSIGNEE", "FUNDS_MANAGEMENT_ROLE"]
}

Role constraints

• The identity root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. is always created with the Admin role and cannot have this role removed.
• Every user must have at least one role assigned.
• Multiple roles can be assigned to a single user. Note that Admin should be used independently because it encompasses all of the permissions of the other roles.

Endpoint access by role

The table in the following section shows the full set of permissions and API endpoints that each role can access.

If a user with a role attempts to call an API that they hold insufficient permissions for, the API will respond with a 403.

Access and authentication

Endpoint(s)	Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	Cards Management Role	Funds Management Role	Access Management Role	Admin
Access (login/out, access tokens)	✓	✓	✓	✓	✓
Passwords (create, update, lost)	✓	✓	✓	✓	✓
Authentication factors (enrol, verify, unlink)	✓	✓	✓	✓	✓
Step-up and confirmation challenges (issue/verify OTPs)	✓	✓	✓	✓	✓

CorporatesCorporates Business entities that can be onboarded as identities on Weavr. Corporate identities represent companies and require Know Your Business (KYB) verification. They can have multiple authorised users and issue cards to card assignees.

Endpoint(s)	Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	Cards Management Role	Funds Management Role	Access Management Role	Admin
Get a corporate				✓	✓
Update a corporate				✓	✓
Send and verify Root userRoot user The individual who creates the identity. For corporate identities, the root user needs to be a legal representative of the corporate such as a director or a representative who has the power of attorney over the company. For consumer identities, the root user is the owner of the identity. Every identity must always have one root user. email				✓	✓
Start and get 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.				✓	✓
Charge a fee to a corporate			✓		✓

ConsumersConsumers Individual persons who can be onboarded as identities on Weavr. Consumer identities represent individual customers and require Know Your Customer (KYC) verification. For consumers, the card owner and card assignee are typically the same person.

Endpoint(s)	Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	Cards Management Role	Funds Management Role	Access Management Role	Admin
All consumer operations					✓

Authorised UsersAuthorised Users Individuals that have been invited by the root user to manage an identity's instruments and transactions. They are not the legal owners of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorised Users.

Endpoint(s)	Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	Cards Management Role	Funds Management Role	Access Management Role	Admin
Create a user				✓	✓
Get all users				✓	✓
Get a user by ID	Own only	Own only	Own only	✓ (all)	✓
Update a user	Own only (excl. roles)	Own only (excl. roles)	Own only (excl. roles)	✓ (all)	✓
Activate and deactivate a user				✓	✓
Send a user invite				✓	✓

note

The remaining endpoints related to email invitations/verification do not require a user so permissions do not apply.

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.

Endpoint(s)	Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	Cards Management Role	Funds Management Role	Access Management Role	Admin
Create a managed card		✓			✓
Get all managed cards	Linked only	✓ (all)	Linked only	Linked only	✓
Get a managed card by ID (non-sensitive details)	Linked only	✓ (all)	Linked only	Linked only	✓
Get a managed card by ID (sensitive details)	Linked only	Linked only	Linked only	Linked only	✓
Update a managed card	Linked only	✓ (all)	Linked only	Linked only	✓
Detokenise card (display sensitive details)	Linked only	Linked only	Linked only	Linked only	✓
Block/unblock card	Linked only	✓ (all)	Linked only	Linked only	✓
Remove a managed card		✓ (all)			✓
Get a managed card statement	Linked only	✓ (all)	✓ (all)	Linked only	✓
Get spend rules for a managed card	Linked only	✓ (all)	Linked only	Linked only	✓
Create/update/delete spend rules		✓ (all)			✓

Physical cardsPhysical 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.

Endpoint(s)	Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	Cards Management Role	Funds Management Role	Access Management Role	Admin
Upgrade a card to physical	Linked only	✓ (all)	Linked only	Linked only	✓
Activate a physical card	Linked only	Linked only	Linked only	Linked only	✓
Get PIN for a physical card	Linked only	Linked only	Linked only	Linked only	✓
Unblock PIN for a physical card	Linked only	✓ (all)	Linked only	Linked only	✓
Replace a damaged physical card	Linked only	✓ (all)	Linked only	Linked only	✓
Report a 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. as lost/stolen, and replace	Linked only	✓ (all)	Linked only	Linked only	✓
Reset contactless limit for a physical card	Linked only	✓ (all)	Linked only	Linked only	✓

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.

Endpoint(s)	Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	Cards Management Role	Funds Management Role	Access Management Role	Admin
All account operations			✓		✓

Beneficiaries

Endpoint(s)	Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	Cards Management Role	Funds Management Role	Access Management Role	Admin
All beneficiary operations			✓		✓

Linked accountsLinked Account An entity in the Weavr system that represents an external bank account or payment service provider (PSP) account which an Identity has verified they own and control. This feature enables users to perform transactions, such as outgoing and incoming wire transfers, between their Linked Accounts and their Managed Accounts as 'self-to-self' transfers.

Endpoint(s)	Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	Cards Management Role	Funds Management Role	Access Management Role	Admin
All linked account operations			✓		✓

Transactions

Endpoint(s)	Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	Cards Management Role	Funds Management Role	Access Management Role	Admin
All Sends, Transfers, and OWT operations			✓		✓

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.

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. follow the same permissions as for the single operation.

Endpoint(s)	Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users.	Cards Management Role	Funds Management Role	Access Management Role	Admin
Bulk management (get, execute, pause, resume, cancel)		✓	✓	✓	✓

Legend:

• ✓ and ✓ (all) = Full access
• "Linked only" = Can only access cards assigned to them
• "Own only" = Can only access their own user record
• Empty = No access