REST API Permissions

The tokens delivered by xivo-auth have a list of permissions associated (ACL), that determine which REST resources are authorized for this token. Each REST resource has an associated required ACL. When you try to access to a REST resource, this resource requests xivo-auth with your token and the required ACL to validate the access.

Syntax

An ACL contains 3 parts separated by dot (.)

• service: name of service, without prefix xivo- (e.g. xivo-confd -> confd).

• resource: name of resource separated by dot (.) (e.g. /users/17/lines -> users.17.lines).

• action: action performed on resource. Generally, this is the following schema:

  • get -> read

  • put -> update

  • post -> create

  • delete -> delete

Substitutions

There are 3 substitution values for an ACL.

• *: replace only one word between dot.

• #: replace one or multiple words.

• me: replace the user_uuid from sent token.

Example

The ACL confd.users.me.#.read will have access to the following REST resources:

GET /users/{user_id}/cti
GET /users/{user_id}/funckeys
GET /users/{user_id}/funckeys/{position}
GET /users/{user_id}/funckeys/templates
GET /users/{user_id}/lines
GET /users/{user_id}/lines/{line_id}
GET /users/{user_id}/voicemail

• service: confd

• resource: users.me.#

• action: read

The ACL confd.users.me.funckeys.*.* will have access to the following REST resources:

DELETE /users/{user_id}funckeys/{position}
GET /users/{user_id}funckeys/{position}
PUT /users/{user_id}funckeys/{position}
GET /users/{user_id}funckeys/templates

• service: confd

• resource: users.me.funckeys.*

• action: *

Where {user_id} is the user uuid from the token.

Available ACLs

The ACL corresponding to each resource is documented. Some resources may not have any associated ACL yet, so you must use {service}.# instead.