> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tesouro.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Roles
> Manage what users can see and do in the FinOps Hub.
## Overview
Roles control what each user can see and do in FinOps Hub and Embedded Banking: from expenses and invoices to payments, accounting configuration, and bank accounts. Every user has exactly one role, either system-provided or custom.
The full set of permissions are documented in the [Permissions reference](/finops/guides/roles/permissions).
## System roles
Tesouro provides four built-in roles available to all organizations. They cannot be modified or deleted.
* **Company admin**: full access to all operations, including user and role management
* **Finance admin**: full AR/AP cycle and payments, without user management or org settings.
* **Bookkeeper**: read-only access to all financial objects, with the ability to export data.
* **Employee**: can manage their own expenses and receipts only.
The table below summarizes what each role can do, derived from the live permission set for each system role:
| Capability | Company admin | Finance admin | Bookkeeper | Employee |
| ---------------------- | --------------------------------------- | ------------------------------- | ------------------------------------- | -------------------- |
| Manage users and roles | Read + Write | — | — | — |
| Org settings | Read + Write | — | — | — |
| Bank accounts | Read + Write | Read (account-gated) | Read | — |
| Linked bank accounts | Read + Write | — | — | — |
| Counterparts | Read + Write | Read + Write | Read | — |
| Invoices (AR) | Read + Write | Read + Write | Read | — |
| Payables (AP) | Read + Write + Pay + Force approve | Read + Write + Pay | Read | — |
| Expenses | Read + Write + Force approve (org-wide) | Own + direct reports | Read (org-wide, incl. direct reports) | Own + direct reports |
| Approval policies | Read + Write | Read | Read | Read |
| Accounting config | Read + Write | — | Read | — |
| Exports | Read + Write | — | Read + Write | — |
| Embedded bank accounts | Full | Read + Transfer (account-gated) | Read | — |
System roles cannot be modified or deleted. `PATCH` and `DELETE` requests on a system role return
`403 Forbidden`.
**Account-gated** means the Finance admin's access to bank accounts and embedded bank accounts is
limited to only the accounts explicitly granted to them. To grant or revoke a user's access to
specific bank accounts, use the [Bulk update
access](/api-reference/bank-accounts/bulk-update-access) endpoint.
## Reporting manager
A reporting manager is a user relationship, not a role or permission. When a user is designated as someone's reporting manager (via the `reportingManagerId` field on the user object), they automatically gain access to that person's expense records.
This is what gives `expense:read:self` and `expense:write:self` their extended reach: "self" covers the user's own expenses **plus** those of their direct reports. No additional permission is required.
Reporting manager access doesn't grant approval rights. The organization's approval policies govern those.
See [Expense approval
policies](/finops/guides/expense-management/setup#define-expense-approval-policies) to configure
approval rules for a reporting manager's team.
## Custom roles
Organizations can create custom roles with any combination of user-assignable permissions. Unlike system roles, custom roles can be updated and deleted.
### Create a custom role
Call `POST /identity/v1/roles` with a partner-level access token:
```sh lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/identity/v1/roles' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"name": "Finance Controller",
"key": "finance_controller",
"description": "Read-only access to payables and receivables for external auditors"
}'
```
The successful response returns the created role object:
```json lines theme={null}
{
"id": "2b7547eb-a028-4e2f-a625-0c4cf30558f0",
"name": "Finance Controller",
"key": "finance_controller",
"description": "Read-only access to payables and receivables for external auditors",
"isSystemRole": false,
"status": "ACTIVE",
"organizationId": "ORGANIZATION_ID",
"icon": null,
"createdDateTime": "2026-06-08T09:00:00.000Z",
"updatedDateTime": "2026-06-08T09:00:00.000Z"
}
```
### Assign permissions to a custom role
After creating the role, assign permissions using `POST /identity/v1/roles/{roleId}/permissions`:
```sh expandable lines theme={null}
curl -X POST 'https://api.sandbox.tesouro.com/identity/v1/roles/ROLE_ID/permissions' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"type": "ASSIGN",
"permissionIds": ["PERMISSION_ID_1", "PERMISSION_ID_2"]
}'
```
Returns `204 No Content` on success. To remove permissions from a role, use `"type": "REMOVE"` with the same endpoint and the permission IDs to revoke.
Permission IDs can be retrieved from `GET /identity/v1/roles/{roleId}/permissions` on any existing role, or from the [Permissions reference](/finops/guides/roles/permissions).
### Assign the role to a user
Assign the role to a user by setting `roleId` on `POST /identity/v1/users` (when creating a user) or `PATCH /identity/v1/users/{userId}` (to update an existing user). See [Organization users](/finops/guides/organizations/users).
### Update a custom role
Call `PATCH /identity/v1/roles/{roleId}` with any subset of `name`, `key`, or `description`:
```sh lines theme={null}
curl -X PATCH 'https://api.sandbox.tesouro.com/identity/v1/roles/ROLE_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"description": "Read-only access to payables, receivables, and payment records for external auditors"
}'
```
### Delete a custom role
Call `DELETE /identity/v1/roles/{roleId}`. Returns `204 No Content` on success. System roles cannot be deleted and return `403 Forbidden`.
```sh lines theme={null}
curl -X DELETE 'https://api.sandbox.tesouro.com/identity/v1/roles/ROLE_ID' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
Deleting a role does not automatically reassign its members. Users who were assigned the deleted
role will have no role and may lose access to the system. Reassign them to another role before or
immediately after deleting.
## Read role data
### List members of a role
`GET /identity/v1/roles/{roleId}/members` returns all users currently assigned to a role. The response is paginated and supports `limit` and `paginationToken` query parameters.
```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/identity/v1/roles/ROLE_ID/members' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
```json lines theme={null}
{
"data": [
{
"userId": "e4e422fc-6956-4fdd-b091-920329f8b92e",
"name": "Gardner Waelchi",
"email": "g.waelchi@summitfinancial.example.com",
"status": "ACTIVE",
"assignedDateTime": "2026-06-08T09:15:00.000Z"
}
],
"nextPaginationToken": null,
"prevPaginationToken": null
}
```
### List permissions on a role
`GET /identity/v1/roles/{roleId}/permissions` returns all permissions assigned to a role.
```sh lines theme={null}
curl -X GET 'https://api.sandbox.tesouro.com/identity/v1/roles/ROLE_ID/permissions' \
-H 'Authorization: Bearer ACCESS_TOKEN'
```
```json lines theme={null}
{
"data": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"key": "payable:read:org",
"name": "Read payables",
"description": "View all payables within the organization"
}
],
"nextPaginationToken": null,
"prevPaginationToken": null
}
```