Skip to main content

​
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 a user role

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. Roles are created by calling POST /roles. The partner-level token and the organization ID are required for this action. In the example below, a new role is created to allow read access to the comment and payable objects: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/roles' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
      "name": "View payables",
      "permissions": {
        "objects": [
          {
            "object_type": "comment",
            "actions": [
              {
                "action_name": "read",
                "permission": "allowed"
              }
            ]
          },
          {
            "object_type": "payable",
            "actions": [
              {
                "action_name": "read",
                "permission": "allowed"
              }
            ]
          }
        ]
      }
    }'
The successful response contains the information about the role, including the role ID that you will require later. 
{
  "id": "2724e6bf-17b8-4462-b2ed-7d3e16c4a133",
  "name": "View payables",
  "permissions": {
    "objects": [
      {
        "object_type": "comment",
        "actions": [
          {
            "action_name": "read",
            "permission": "allowed"
          }
        ]
      },
      {
        "object_type": "payable",
        "actions": [
          {
            "action_name": "read",
            "permission": "allowed"
          }
        ]
      }
    ]
  },
  "status": "active",
  "created_at": "2022-09-28T12:06:01.589258+00:00",
  "updated_at": "2022-09-28T12:06:01.589272+00:00"
}
For the full list of permissions, see List of permissions. The information about the created role can be retrieved later by calling GET /roles/{role_id}.

​
Create an organization user

To create an organization user, call POST /entity-users. Specify the organization ID in the X-Organization-Id request header and the user data in the request body. The role_id field must be populated by the ID of the role created earlier. The request must be authorized using a partner-level access token: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/entity-users' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer YOUR_APP_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "login": "Gardner.Waelchi",
       "first_name": "Gardner",
       "last_name": "Waelchi",
       "role_id": "946141f3-ca01-44dc-b1a6-1024aa71f978",
       "email": "g.waelchi@example.com",
       "phone": "+15551234567",
       "title": "Mr."
     }'
The successful response contains the created organization user: 
{
  "id": "e4e422fc-6956-4fdd-b091-920329f8b92e",
  "role_id": "946141f3-ca01-44dc-b1a6-1024aa71f978",
  "userpic": null,
  "login": "Gardner.Waelchi",
  "first_name": "Gardner",
  "last_name": "Waelchi",
  "status": "active",
  "created_at": "2022-04-21T14:39:39.554700+00:00",
  "updated_at": "2022-04-21T14:39:39.554710+00:00",
  "email": "g.waelchi@example.com",
  "phone": "+15551234567",
  "userpic_file_id": null
}

​
Set the profile picture

To set the organization user’s profile picture, call POST /files and provide the file as a multipart/form-data request. Use the file field to pass the file, and set the file_type field to userpics: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/files' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Authorization: Bearer ACCESS_TOKEN'
     -H 'Content-Type: multipart/form-data' \
     -F 'file=@userpic.png;type=image/png' \
     -F 'file_type=userpics'
The response returns the document ID assigned to the uploaded file. Note it down as you will need it later. 
{
  "id": "d8e29d12-c045-470d-a984-08e158aab812",
  "created_at": "2024-01-18T09:48:15.782992+00:00",
  "updated_at": "2024-01-18T09:48:15.783001+00:00",
  "file_type": "userpics",
  "md5": "bbff083b8447c2854258a4582fa73dea",
  "mimetype": "image/png",
  "name": "userpic.png",
  ...
  "size": 57190,
  "url": "https://<bucketname>.s3.<region>.amazonaws.com/path/to/file.png"
}
To connect the uploaded picture to the organization user, call PATCH /entity-users/{entity_user_id} and provide the document ID in the userpic_file_id field in the request body: 
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/entity-users' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer YOUR_APP_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "userpic_file_id": "d8e29d12-c045-470d-a984-08e158aab812"
     }'
The uploaded files can also be retrieved or deleted, by calling GET /files/{file_id} and DELETE /files, respectively.

​
List all organization users

To get information about all the organization users managed by the organization, call GET /entity-users.

​
Retrieve an organization user

To get information about a specific organization user, call GET /entity-users/{entity_user_id}.

​
Edit an organization user

To edit an existing organization user, call PATCH /entity-users/{entity_user_id}.

​
Delete an organization user

To delete an existing organization user, call DELETE /entity-users/{entity_user_id}.

​
Get an organization user token

To make API calls on behalf of an organization user, you need to use an access token of that user. To get this token, call POST /auth/token with the following request body: 
{
  "grant_type": "entity_user",
  "client_id": "YOUR_PARTNER_API_KEY",
  "client_secret": "YOUR_PARTNER_API_SECRET",
  "entity_user_id": "USER_ID"
}
For example: 
curl -X POST 'https://api.sandbox.tesouro.com/v1/auth/token' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'Content-Type: application/json' \
     -d '{
       "grant_type": "entity_user",
       "client_id": "2e0c68d6-00b7-447d-b26c-415bbcbfc026",
       "client_secret": "cf0de0bd-a59e-473f-a3dd-db5924bd8622",
       "entity_user_id": "0c76febf-aabb-451a-aabb-ea3b47689dc1"
     }'
The successful response contains the access token for the specified user: 
{
  "access_token": "L8qq9PZyRg6ie...",
  "token_type": "Bearer",
  "expires_in": 86400
}
This token can be sent in the Authorization: Bearer TOKEN request header as an alternative to using a partner-level token.

​
Get and update the authenticated user info

The authenticated organization user can check all its own information by calling GET /entity-users/me. The request must be authorized using an organization user level-access token: 
curl -X GET 'https://api.sandbox.tesouro.com/v1/entity-users/me' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ENTITY_USER_ACCESS_TOKEN'
The successful response returns the information about the authenticated organization user, including the user ID, role, and other details: 
{
  "id": "24c9b573-7e61-4083-9115-b162cc4b9421",
  "role_id": "84f48b5c-c24f-48f8-9c33-411a990512c9",
  "login": "Hadley80",
  "first_name": "Amie",
  "last_name": "Thiel",
  "status": "active",
  "created_at": "2022-09-21T14:59:00.780705+00:00",
  "updated_at": "2022-09-21T14:59:00.780715+00:00",
  "userpic_file_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
The authenticated organization user can also make changes to its own information by calling PATCH /entity-users/me, passing the information they wish to update. In the example below, the last_name field is being updated. The request must be authorized using an organization user level-access token: 
curl -X PATCH 'https://api.sandbox.tesouro.com/v1/entity-users/me' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ENTITY_USER_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{
       "last_name" : "Scott"
     }'
The successful response returns the updated user object.

​
Get the role of the authenticated organization user

To retrieve information about the role and permissions assigned to the authenticated organization user, call GET /entity-users/my-role: 
curl -X GET 'https://api.sandbox.tesouro.com/v1/entity-users/my-role' \
     -H 'X-Finops-Version: 2025-06-23' \
     -H 'X-Organization-Id: ORGANIZATION_ID' \
     -H 'Authorization: Bearer ENTITY_USER_ACCESS_TOKEN' \
     -H 'Content-Type: application/json' \
The successful response returns the role object associated with the authenticated organization user.