No results

Token permissions

Tokens are the primary way to authenticate with the API. They can be given permissions to access specific resources.

When you send a request to the API, you should include a token value in the x-api-token header.

We can optionally restrict tokens by a list of IP addresses. This means the token will only work when the request is made from one of the specified IP addresses.

Tokens can also be given an expiry date.

Permissions

Each token can have a list of permissions. These permissions will be evaluated in the order in which they're defined, with later permissions potentially overriding or modifying earlier ones.

Each permission has the following structure:

[
0: {
mode: "allow"
action: "*"
}
]
  • required
    mode'allow' | 'block'Whether this permission is allowing or blocking something.
  • required
    action
    | '*'
    | 'create'
    | 'view'
    | 'update'
    | 'delete'
    | 'register'
    | 'authenticate'
    | 'create-with-identity'
    | 'view-with-identity'
    | 'update-with-identity'
    | 'delete-with-identity'

    The action covered by this permission. The value '*' refers to "all actions".

    The register and authenticate actions allow users to register and authenticate identities, respectively.

    The create-with-identity, view-with-identity, update-with-identity, and delete-with-identity actions allow users to perform the specified action on items, but only if they're authenticated using an identity. In this case, any items they create will be associated with the identity, and any items being viewed, updated, or deleted must belong to the identity.

  • resourceType'list' | 'item' | 'index' | 'identity' | 'event' | 'stats'The type of resource this permission applies to. The values 'event' and 'stats' are only applicable when the action is 'view', and refer to the ability to view events and stats, respectively.
  • listIdsstring[]

    An array of list ids. This attribute can be omitted if the permission does not apply to a particular list, for example if the action is 'create' and the resourceType is 'list' (which means the permission allows lists to be created).

    Additionally, the array can contain the value '*', which means the permission applies to all lists.

  • itemIdsstring[]

    An array of item ids. This attribute can be omitted if the permission is not applicable to items.

    Additionally, the array can contain the value '*', which means the permission applies to all items.

  • indexIdsstring[]

    An array of index ids. This attribute can be omitted if the permission is not applicable to indexes.

    Additionally, the array can contain the value '*', which means the permission applies to all indexes.

  • identityIdsstring[]

    An array of identity ids. This attribute can be omitted if the permission is not applicable to identities.

    Additionally, the array can contain the value '*', which means the permission applies to all identities.

  • groupsstring[]

    An array of group names. This attribute can be omitted if the permission is not applicable to groups.

    Additionally, the array can contain the value '*', which means the permission applies to all groups.

    This allows you to restrict the identities that can register and authenticate when using a particular token.

2024-11-15