Skip to content

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

ScopeGranted access
read_onlyAll GET endpoints (except legal, keys and admin) End user oriented
read_writeAll PUT, POST, and DELETE endpoints (except legal, keys and admin) End user oriented
read_allAll GET endpoints Use carefully
adminAPI Configuration endpoints Use carefully
keysEncryption keys management endpoints
legalKYC, users and end user documents endpoints
support_user_managementSupport users endpoints
Thumbs icon

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

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.

js
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

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

Example

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

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

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

js
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.
Lock icon

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.