Users and roles
How is access managed for users of our API?
Users represent the credentials and access permissions for anyone or anything that needs to interact with our platform. Each user serves three key functions:
Authentication - Defines how the user authenticates (email or API key, see Authentication)
Authorization - Contains specific permissions that control what actions the user can perform
Audit tracking - Identifies which user performed each action in our audit trails for compliance, regulatory, troubleshooting, and other needs
Users can represent either human employees or technical systems (backend services, monitoring tools, data synchronization jobs, etc.). You decide how granular to make your user accounts based on your regulatory needs.
Roles and permissions
Tokenization involves multiple workflows with varying levels of sensitivity, often performed by different departments or external parties. Our access control system lets you create precise permissions for each user while making management scalable through roles.
Permissions
A permission allows a user to perform a specific action. Permissions generally align with our API structure and control three types of access:
View lists - See collections of objects (e.g., view all investors)
View individual items - Access specific objects by ID (useful when a user should only see certain investors, not all)
Perform actions on objects:
Create (e.g., add a new asset)
Modify (e.g., change an investor's verification status)
Deactivate (e.g., disable a user account)
Managing permissions in your UI
To simplify permission management in any UI you build, we provide a streamlined approach using the PUT method:
Retrieve all available permissions using our dedicated endpoint that lists every possible permission
Build a checkbox interface where administrators can select which permissions to grant
Submit the complete selection via our PUT endpoint when the administrator saves changes
This approach replaces the user's entire permission set with the selected permissions, eliminating the need to add or remove permissions individually. Each submission completely overwrites the previous permission list based on the checkbox selections, making permission management straightforward and error-free.
Roles
When multiple users need similar access levels, you can group permissions into roles for easier management. For example, a "Compliance Officer" role might include:
Create investor records
Verify investor information
Add investors to whitelists
Each time you onboard a new compliance team member, simply assign this role instead of configuring individual permissions.
Roles update dynamically - when you modify permissions within a role, the changes automatically apply to all users with that role assigned.
Combining permissions and roles
You can assign both roles and individual permissions to the same user. For instance, you might assign the "Compliance Officer" role to a department head, then add specific permissions like "Deactivate investor" that only they should have.
Users can have multiple roles and additional individual permissions as needed.
The diagram below shows how users, roles, and permissions work together:
Last updated