> For the complete documentation index, see [llms.txt](https://taas-docs.stokr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://taas-docs.stokr.io/api-overview/users-and-roles.md).
# Users and roles
{% columns %}
{% column width="50%" %}
## Users
{% endcolumn %}
{% column width="50%" %}
{% endcolumn %}
{% endcolumns %}
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](/general-api-principles/authentication.md))
* **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:
1. **Retrieve all available permissions** using our dedicated endpoint that lists every possible permission
2. **Build a checkbox interface** where administrators can select which permissions to grant
3. **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:
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://taas-docs.stokr.io/api-overview/users-and-roles.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.