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