Roles

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.

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 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 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:

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:

{
  "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:

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.

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.

Update a custom role

Call PATCH /identity/v1/roles/{roleId} with any subset of name, key, or description:

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.

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.

curl -X GET 'https://api.sandbox.tesouro.com/identity/v1/roles/ROLE_ID/members' \
     -H 'Authorization: Bearer ACCESS_TOKEN'

{
  "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.

curl -X GET 'https://api.sandbox.tesouro.com/identity/v1/roles/ROLE_ID/permissions' \
     -H 'Authorization: Bearer ACCESS_TOKEN'

{
  "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
}

Getting started

Embedded components

Authentication

Roles & permissions

Manage organizations

Common objects

Accounts payable

Accounts receivable

Expense management

Payments

Advanced

Accounting integrations

Overview

System roles

Reporting manager

Custom roles

Create a custom role

Assign permissions to a custom role

Assign the role to a user

Update a custom role

Delete a custom role

Read role data

List members of a role

List permissions on a role

​Overview

​System roles

​Reporting manager

​Custom roles

​Create a custom role

​Assign permissions to a custom role

​Assign the role to a user

​Update a custom role

​Delete a custom role

​Read role data

​List members of a role

​List permissions on a role

Overview

System roles

Reporting manager

Custom roles

Create a custom role

Assign permissions to a custom role

Assign the role to a user

Update a custom role

Delete a custom role

Read role data

List members of a role

List permissions on a role