Skip to content

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 /merchants/{id}/projects/{id}/ and still see <redacted> instead of the API key.

Path permissions

A path permission maps an API path, without the /v1 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

OnFieldWhat it does
Merchantbase_permissionsThe maximum for everything in the merchant. Only you, the operator, set it, with the Admin portal or the Boarding API.
ProjectpermissionsWhat the API key of the project may do. A new project without permissions gets the base permissions of its merchant.
RolepermissionsWhat the users with the role may do.
UserpermissionsDeprecated: 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

  • self stands for the merchant, project or user of the credentials: /merchants/self/ is the merchant of the API key or user.
  • * matches one part of a path: /search/*/ matches /search/orders/, not /search/orders/export/.
  • /** matches any number of parts, including none: /orders/** matches /orders/, /orders/{id}/ and everything below it.
  • A trailing slash doesn't matter.
  • The Boarding API is under /admin: /admin/merchants/** covers /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: /merchants/self/projects/** comes before /merchants/self/projects/ 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 /merchants/self/projects/ returns project Y only. With /merchants/self/projects/** instead of /merchants/self/projects/*/**, 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_permissions 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

ConditionAccess
The field isn't listedRead and write
read is missingread is true
write is missingwrite 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 /merchants/{id}/projects/{id}/, Ginger drops the fields the user can't write and applies the rest of the update.
  • When the user calls an endpoint for the field itself, such as POST /merchants/{id}/projects/{id}/apikeys/, the request is refused with 403 Forbidden.

Protected fields

These project fields can't be restricted: id, created, modified, merchant_id, 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