Permissions
What an API key or user may do: path permissions on endpoints, and field permissions on the fields of a project.
Permissions decide what an API key or a user may do. This page is the reference for both kinds:
- Path permissions decide which endpoints, and which HTTP methods on them, a project or user may call.
- Field permissions decide which fields of a project a user may see or change.
They are independent: a user may call GET / and still see <redacted> instead of the API key.
Path permissions
A path permission maps an API path, without the / prefix, to the HTTP methods allowed on it:
{
"/merchants/self/**": { "GET": true },
"/orders/**": { "GET": true, "POST": true, "PUT": true, "DELETE": true },
"/reports/**": { "GET": true },
"/search/*/": { "POST": true }
}The methods are GET, POST, PUT, DELETE, or * for all four. In the Admin portal, Create, Read, Update and Delete stand for POST, GET, PUT and DELETE, and the path is the Command path.
Where permissions are set
| On | Field | What it does |
|---|---|---|
| Merchant | base_ | The maximum for everything in the merchant. Only you, the operator, set it, with the Admin portal or the Boarding API. |
| Project | permissions | What the API key of the project may do. A new project without permissions gets the base permissions of its merchant. |
| Role | permissions | What the users with the role may do. |
| User | permissions | Deprecated: give users roles instead. A user with roles has no permissions of its own. |
Ginger removes what the base permissions of the merchant don't allow when you save the permissions of a project, role or user. A project or user can't change its own permissions, and a user can't change its own roles. Through the Merchant Self-Service API, you can't create a role, or create or change a user, with more permissions than you have yourself.
The permissions of a user are those of all its roles together: when two roles set the same path, a method allowed by either role is allowed.
Paths
selfstands for the merchant, project or user of the credentials:/is the merchant of the API key or user.merchants/ self/ *matches one part of a path:/matchessearch/ */ /, notsearch/ orders/ /.search/ orders/ export/ /matches any number of parts, including none:** /matchesorders/ ** /,orders/ /and everything below it.orders/ {id}/ - A trailing slash doesn't matter.
- The Boarding API is under
/:admin /coversadmin/ merchants/ ** /.v1/ admin/ merchants/ … /covers every API.**
How a request is checked
Ginger checks the permissions in reverse alphabetical order of their path, and the first path that matches the request and lists its method decides. If no path matches, the request is refused with 403 Forbidden.
In practice, a literal part sorts before * at the same position, so a specific path usually wins over a wildcard. Mind that / also matches the path it's on: / comes before / and also decides for the list of projects.
Don't mix * with methods on one path
For {"*": true, "POST": false}, the outcome for POST depends on the order of the keys. Set either * or separate methods on a path.
Example: limit a user to one project
A user lists the projects it may read. These permissions let a user see the merchant, list projects, and use project Y only:
{
"/merchants/self/": { "GET": true },
"/merchants/self/projects/": { "GET": true },
"/merchants/self/projects/*/**": { "GET": false },
"/merchants/self/projects/Y/**": { "GET": true }
}GET / returns project Y only. With / instead of /, the list itself would be refused.
Field permissions
Field permissions limit what a user sees and changes in the fields of a resource. Set them in field_ on a role or a user, next to permissions:
{
"field_permissions": {
"projects": {
"apikey": { "read": false, "write": false },
"contract.silverflow.fields.acceptor": { "read": true, "write": false }
}
}
}The structure is resource, then field, then read and write. projects is the only resource. Use dots for nested fields: contract.silverflow.fields.acceptor is the acceptor key in the contract.silverflow.fields object.
Field permissions apply to users. API keys aren't affected.
Defaults
| Condition | Access |
|---|---|
| The field isn't listed | Read and write |
read is missing | read is true |
write is missing | write is the value of read |
Several roles
For field permissions, the most restrictive setting wins: if any role of the user, or the user itself, denies access to a field, access is denied. This is the opposite of path permissions, where an allowed method wins.
Reading a field
A field the user can't read keeps its key in the response, with the value <redacted>:
{
"id": "b8a1c2d4-1234-4c5d-9e8f-0123456789ab",
"apikey": "<redacted>",
"trade_name": "Acme Coffee"
}A field that isn't in the resource stays absent.
Writing a field
- When the user updates the whole resource, such as
PUT /, Ginger drops the fields the user can't write and applies the rest of the update.merchants/ {id}/ projects/ {id}/ - When the user calls an endpoint for the field itself, such as
POST /, the request is refused withmerchants/ {id}/ projects/ {id}/ apikeys/ 403 Forbidden.
Protected fields
These project fields can't be restricted: id, created, modified, merchant_, status and permissions. Field permissions that list them are refused with a validation error.
Example: a support role
{
"name": "Support agent",
"permissions": {
"/merchants/self/projects/*/": { "GET": true, "PUT": true }
},
"field_permissions": {
"projects": {
"apikey": { "read": false, "write": false },
"contract.silverflow.fields.acceptor": { "read": true, "write": false }
}
}
}Users with this role can view and update projects, but:
- see
<redacted>instead of the API key, and can't generate a new one; - see the Silverflow acceptor, but can't change it;
- read and write all other fields.
Next steps
- Create an admin API key.
- Manage roles and users with the Merchant Self-Service API.