> ## 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.

# Organization users

> Learn how to manage your customers' organization users.

## Overview

Once the customers are [mapped out as organizations](/finops/guides/organizations/index), 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](/finops/guides/authentication/client-credentials).

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.

```sh lines theme={null}
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:

```json lines theme={null}
{
  "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)](/finops/guides/authentication/overview):

```sh lines theme={null}
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:

```json lines theme={null}
{
  "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](#get-an-organization-user-token):

```sh lines theme={null}
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

<Note>
  For an introduction to the role model, system roles, and custom role management, see the [Roles guide](/finops/guides/roles/index).
</Note>

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.