Access rights management (/permissions/...)
Flexible API access restriction: you can prohibit the user from using an entire method or individual fields in a request without re—launching the application.
Content
How it works
Description of data structures
Example
Features
Resources of the "Permissions" section
How it works
Access is described by three entities:
Resource — which endpoint is protected (URL + HTTP method).
Rule — what exactly is forbidden for this resource: the entire method or specific fields.
Group — a set of rules for convenient assignment to multiple users at once.
A rule is applied to a user either directly or via a group.
For each request the system selects matching rules and decides whether to allow the request or return 403.
Each record belongs to one of the contexts:
Context | Managed by | Restrictions apply to |
|---|---|---|
Dealer | Dealer | Only to their own customers and their employees |
Customer | Customer | Only to their own employees |
Contexts are isolated: a dealer does not see rules of another dealer, and a customer does not see rules of another customer.
Description of data structures
Example
We need to forbid an administrator with id = 100 from deleting users via the API.
Step 1. Create a resource
Create a resource for DELETE /application/<id>:
POST /api/ver1.0/permissions/resources/
Content-Type: application/json
{
"endpoint": "/extension/{extension_id}/agent/{agent_id}",
"method": "DELETE",
"login_type": "extension"
}Example response:
{
"id": 42,
"endpoint": "/extension/{extension_id}/agent/{agent_id}",
"method": "DELETE",
"login_type": "extension"
}Step 2. Create a rule that blocks the entire method
POST /api/ver1.0/permissions/rules/
Content-Type: application/json
{
"resource_id": 42,
"action": "block_all"
}Example response:
{
"id": 7,
"resource_id": 42,
"action": "block_all",
"blocked_fields": []
}Step 3. Assign the rule to the user
PUT /api/ver1.0/permissions/users/100/rules/
Content-Type: application/json
{
"rule_ids": [7]
}Done: when the user tries to call
DELETE /extension/{extension_id}/agent/{agent_id}user 100 will receive:
HTTP/1.1 403 Access denied: method blockedOption: block only specific fields
If you don’t want to block the entire method, but only some of the data (for example, the password field), use block_fields in step 2:
POST /api/ver1.0/permissions/rules/
Content-Type: application/json
{
"resource_id": 42,
"action": "block_fields",
"blocked_fields": ["password"]
}To assign rules to multiple users at once, it is convenient to group them:
POST /api/ver1.0/permissions/groups/
Content-Type: application/json
{ "name": "no-delete" }
PUT /api/ver1.0/permissions/groups/8/rules/
Content-Type: application/json
{ "rule_ids": [7] }
PUT /api/ver1.0/permissions/users/100/groups/
Content-Type: application/json
{ "group_ids": [8] }Features
Changes take effect automatically.
Replacement, not addition.
The following operations completely replace the set. An empty array clears all bindings:PUT .../groups/{id}/rules/PUT .../users/{id}/groups/PUT .../users/{id}/rules/
You cannot go beyond your context.
For example, a customer cannot create a rule withlogin_type = "dealer".
Such an attempt returns403.Links only within the same context.
A dealer’s group cannot be linked to a rule that belongs to another dealer.Cascading delete.
Deleting a dealer/customer automatically deletes all their resources, rules, and groups.Creation rate limit.
No more than 100 requests per hour per user forPOSToperations.
If exceeded —429 Too Many Requests.
“Permissions” section resources
All routes below are available in two contexts:
Context | Prefix |
|---|---|
Dealer |
|
Customer |
|
Dealer and customer can use @me instead of their own identifier.