Organization users

Overview

Once the customers are mapped out as organizations, the next step is to start mapping out their employees to the corresponding organization users in the Tesouro platform.

Create an organization user

To create an organization user, call POST /identity/v1/users. The request must be authorized using a partner-level access token. By default the user is created in your own organization. To create the user in a descendant organization instead, set that organization’s ID in the optional X-Organization-ID request header. You must have visibility into the target organization.

curl -X POST 'https://api.sandbox.tesouro.com/identity/v1/users' \
     -H 'X-Organization-ID: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "email": "g.waelchi@summitfinancial.example.com",
       "name": "Gardner Waelchi",
       "status": "INVITED"
     }'

The successful response contains the created organization user:

{
  "id": "e4e422fc-6956-4fdd-b091-920329f8b92e",
  "email": "g.waelchi@summitfinancial.example.com",
  "name": "Gardner Waelchi",
  "status": "INVITED",
  "isExpenseApprover": false,
  "organizationId": "ORGANIZATION_ID",
  "createdAt": "2026-06-08T09:15:00.000Z"
}

Setting status to INVITED sends the user an invitation email with a one-time link to complete sign-in. Setting it to ACTIVE provisions the user immediately; use this when your platform handles authentication and the user will arrive with a valid JWT.

List all organization users

To get information about all the organization users managed by the organization, call GET /identity/v1/users.

Retrieve an organization user

To get information about a specific organization user, call GET /identity/v1/users/{userId}.

Edit an organization user

To edit an existing organization user, call PATCH /identity/v1/users/{userId}.

Disable or enable an organization user

Organization users are not deleted. To revoke a user’s access, call POST /identity/v1/users/{userId}/disable. To restore access, call POST /identity/v1/users/{userId}/enable.

Get an organization user token

To make API calls on behalf of an organization user, exchange the user’s JWT for a Tesouro access token using OAuth 2.0 Token Exchange (RFC 8693):

curl --location 'https://api.sandbox.tesouro.com/openid/connect/token' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
     --data-urlencode 'client_id=YOUR_CLIENT_ID' \
     --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
     --data-urlencode 'subject_token=USER_JWT_TOKEN' \
     --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token'

The subject_token must be a JWT from your OIDC provider with the user’s stable identifier in the sub claim and their email in the email claim. The successful response contains the access token for the specified organization user:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

This token can be sent in the Authorization: Bearer TOKEN request header to make API calls on that user’s behalf.

Get the authenticated user info

The authenticated organization user can check all its own information by calling GET /identity/v1/users/me. The request must be authorized using an organization user level-access token:

curl -X GET 'https://api.sandbox.tesouro.com/identity/v1/users/me' \
     -H 'Authorization: Bearer USER_ACCESS_TOKEN'

The response includes the user’s assigned role and the effective permissions granted by that role.

Roles and permissions

For an introduction to the role model, system roles, and custom role management, see the Roles guide.

Every organization user must have a role. A role defines the permissions that a user has to access and update the organization’s resources in Tesouro. When a token is issued for an organization user, it inherits the permissions of their assigned role. If no role is explicitly assigned to a user, the organization’s default user role is used instead.

Getting started

Embedded components

Authentication

Roles & permissions

Manage organizations

Common objects

Accounts payable

Accounts receivable

Expense management

Payments

Advanced

Accounting integrations

Organization users

Overview

Create an organization user

List all organization users

Retrieve an organization user

Edit an organization user

Disable or enable an organization user

Get an organization user token

Get the authenticated user info

Roles and permissions

​Overview

​Create an organization user

​List all organization users

​Retrieve an organization user

​Edit an organization user

​Disable or enable an organization user

​Get an organization user token

​Get the authenticated user info

​Roles and permissions

Overview

Create an organization user

List all organization users

Retrieve an organization user

Edit an organization user

Disable or enable an organization user

Get an organization user token

Get the authenticated user info

Roles and permissions