# Scopes & Permissions

A Scope is similar to a permission, depending on the scope you may or may not be able to see and alter certain data. Each user can have one or multiple scopes.

All endpoints are scope-restricted, you need to use an appropriate scope to access an endpoint.

# Available scopes

Scope	Granted access
`read_only`	All `GET` endpoints (except `legal`, `keys` and `admin`) End user oriented
`read_write`	All `PUT\|POST\|DELETE` endpoints (except `legal`, `keys` and `admin`) End user oriented
`read_all`	All `GET` endpoints Use carefully
`admin`	API Configuration endpoints Use carefully
`keys`	Encryption keys management endpoints
`legal`	KYC, users and end user documents endpoints
`support_user_management`	Support users endpoints

Best practice – Align your Scopes with the default Roles

The Dashboard comes with a set of Roles, which are a concatenation of the existing Scopes.

As a consequence, Treezor advises you concatenate Roles in the same way for specific developments.

# Scope selection

The scope selection happens when you authenticate, scopes get embedded in the JWT used for subsequent requests to the API.

During the authentication, you have the choice to either :

# A) Specify the desired scopes

In this case, your are provided with the intersection of the desired scopes and the user's available scopes.

The requested scope are expected in the scope request parameter. If more than one scope is requested, they should be space separated (e.g., admin read_all).

Consider the following desired scopes and user scopes.

user_scopes = ['A', 'B', 'C'];
desired_scopes = ['A', 'B', 'D'];

1
2

The returned token will cover scopes that are present in both : user scopes and desired scopes

returned_scopes = ['A', 'B'];

# Example

curl -X POST {baseUrl}/oauth/token \
	--form 'grant_type="client_credentials"' \		# mandatory
	--form 'client_id="{yourClientId}"' \			# mandatory
	--form 'client_secret="{yourClientSecret}"' \	# mandatory
	--form 'scope="admin"'							# optional, if you want a specific scope

1
2
3
4
5

# B) Don't specify anything

In this case, you are provided with all of the user's scopes.

Consider the following user scopes and no desired scopes.

user_scopes = ['A', 'B', 'C'];

The returned token will cover all of the user's scopes (so be careful!)

returned_scopes = ['A', 'B', 'C'];

# Scopes behavior

# End-user scopes

When using end-user oriented scopes (read_only or read_write without other scopes), the API only returns information related to the authenticated user.

Consider the following requests, made with the read_only scope:

GET /wallets/ will return the wallets of the authenticated user (or his children's wallets).
GET /documents/ will return the documents of the authenticated user (or his children's wallets).
GET /card/123 will return the card of id 123 if it's owned by the authenticated user, and a forbidden error otherwise.

# Machine scopes

When using machine oriented scope (read_all), the API applies no restrictions whatsoever to the returned informations.

Consider the following requests, made with the read_all scope:

GET /wallets/ will return ALL the wallets of ALL users.
GET /documents/ will return ALL the documents of ALL users.
GET /card/123 will return the card of id 123 no matter who owns it.

Security – read_all scope should only be used when absolutely necessary

Don't provide this scope in the end users JWT. This scope is intented for Support users and machine-to-machine calls.

← Authentication HTTP Status codes →