Skip to main content

Permissions

Permissions allow you to control what a user (or a data provider or anyone else connecting to the server) can and can't do. Here's how they work:

When a user connects, she provides a JWT to authenticate herself. You can learn more about this in the authentication guide. This JWT can contain a field called per that specifies which actions the user can perform for each id pattern in each realm.

Structure​

... phew - that sounded complicated. But no worries, we'll go through it step by step. Here's what a token with permissions would look:

{
    // user john doe is a delivery driver in London
    "sub": "johndoe-123",
    // here are his permissions
    "per": {
        // these relate to the realm "london"
        "london": {
            // john can (R)ead all the other delivery drivers position in the app
            "deliveryRiders/*":"R",
            // but he can only (C)reate and (U)pdate information for himself
            "deliveryRides/johndoe-123": "CU"
        }
    }
}

Realm​

A realm is a space within which something happens. All other concepts such as objects, areas, subscriptions, instructions etc. exist within the concept of a realm. You can learn more about realms here.. You can specify permissions for each realm individually by using their id, e.g. london or you can use a wildcard * to specify permissions for all realms.

Id Pattern​

Every object, area, instruction, subscription etc. is identified by a unique id. Ids can contain slashes that group them into categories, e.g. cars/mycar-abc123 or deliveryRiders/contractors/johnDoe.

IdPatterns let you specify entire categories rather than just individual ids, e.g. cars/* or deliveryRiders/*/johnDoe. Here are the rules for id patterns:

  • Id patterns are independent of object types. They apply to objects, areas, etc. equally
  • Exact matches, e.g. abcd-1234 or cars/audi/myaudi-3456 apply only to that specific ids
  • An asterisk * acts as a wildcard selector.
  • An asterisk before */sensors or between slashes cars/*/mycar means this particular segment of the id.
  • An asterisk at the end of a pattern cars/* means anything after this, regardless of slashes.
  • Asterisks can only denote sections between slashes

Actions​

There are five actions you can permission per ID pattern. These are expressed as strings of the uppercase letters CRUDP. The order of these do not matter. The actions stand for

  • Create: This client can create new objects, areas, instructions, subscriptions or tasks.
  • Read: This client can read entities, e.g. via realm.object.get(id) or via list, search or subscribe
  • Update: This client can update the location, data, shape, instruction content etc. of existing entitites
  • Delete: This client can delete existing areas, instructions, objects etc.
  • Publish: This client can publish events using the realm's pub/sub mechanism