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, and 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. Treezor advises you create 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
• B) Don't specify anything

A) Specify the desired scopes

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

The requested scopes 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'];

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

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

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 – Only use read_all scope when absolutely necessary

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