Roles & Permissions

Response and Error Codes

The API will always return a 2xx response code for successful requests, while malformed or failed requests will return either a 4xx or 5xx response code along with a JSON response containing:

  • error: the type of error
  • description (optional): a longer description of the error.

The exact response codes returned will vary with each request and endpoint.

Successful response codes include:

  • 200 Request was successful.
  • 201 Request was processed and a new resource was created.
  • 204 Request was understood, but there is no content to be returned.

In the case of a 4xx error, you should fix the problem with your request. Specific error codes and their meanings are detailed below:

  • 400 Request body is malformed (invalid JSON).
  • 403 User making the request is not authorized to access the resource.
  • 404 Requested resource is not found.
  • 401 Request unauthorized.

401 errors may be returned if the token is invalid at any time.

In the case of a 5xx error, you should retry later.

Authentication

Access to the Roles and Permissions API is determined by the same JWT used to make requests to the chatkit servers. A su token with the su claim should be presented when interacting with the API, more information on JWTs and the su token can be found here. The server SDKs have all the necessary utilities and methods to access the API. However, if you are not using one of the SDKs, make sure the Authorizationheader is present with the Bearer claim.

Endpoints

There are endpoints provided for roles and user roles.

To learn more about these concepts, refer to the roles & permissions section of the docs.

Requests should be sent to

https://us1.pusherplatform.io/services/chatkit_authorizer/v1/:instance_id

appended with the right endpoint for the resource you're interested in. Your instance_id is available from your application dashboard. Your instance_id is the third component of your instanceLocator, for example "v1:us1:instance_id".

Roles

Creating a Role

POST /roles
Request Body

A JSON object with the following keys:

  • scope (string|required): Scope of the new role; one of global or room.
  • name (string|required): Name of the new role.
  • permissions (array|required): Permissions assigned to the role.
Example Request
$ curl -X POST \
  https://us1.pusherplatform.io/services/chatkit_authorizer/v1/:instance_id/roles \
  -d '{"name": "Admin", "scope": "global", "permissions": ["room:join", "room:leave"]}'
Response Body

None

Response Codes

201, 400, 503

Get Roles

GET /roles
Example Request
$ curl https://us1.pusherplatform.io/services/chatkit_authorizer/v1/:instance_id/roles
Response Body
1
2
3
4
5
6
7
[
  {
    "name": "admin",
    "permissions": ["room:create", "user:update"],
    "scope": "global"
  }
]
Response Codes

200, 500, 503

Deleting a Role

DELETE /roles/:role_name/scope/:scope_type
Request Body

None

Example Request
$ curl -X DELETE \
  https://us1.pusherplatform.io/services/chatkit_authorizer/v1/:instance_id/roles/:role_name/scope/:scope_type
Response Body

None

Response Codes

204, 400, 503

User Roles

Setting a User Role

PUT /users/:user_id/roles
Request Body

A JSON object with the following keys:

  • name (string|required): Name of the role.
  • room_id (string|optional): The ID of the room you want to set the user role for. If no room_id value is provided then the scope will be global.
Example Request
$ curl -X PUT \
  https://us1.pusherplatform.io/services/chatkit_authorizer/v1/:instance_id/users/:user_id/roles \
  -d '{"name": "Admin"}'
Response Body

None

Response Codes

200, 201, 400, 500, 503

Get User Roles

GET /users/:user_id/roles
Request Body

None

Example Request
$ curl -X GET \
  https://us1.pusherplatform.io/services/chatkit_authorizer/v1/:instance_id/users/:user_id/roles
Response Body

A list of all the user roles associated with the user_id

Example

1
2
3
4
5
6
7
[
  {
    "role_name": "admin",
    "permissions": ["room:create", "user:update"],
    "scope": "global"
  }
]
Response Codes

200, 400, 503

Delete User Role

DELETE /users/:user_id/roles

Query Parameters

  • room_id (string|optional): The ID of the room you want to delete the user role for. If not provided then if theuser_id has an associated (non-default) user role at the global scope, that will be deleted.
Example Request
$ curl -X DELETE \
  https://us1.pusherplatform.io/services/chatkit_authorizer/v1/:instance_id/users/:user_id/roles?room_id=1
Response Body

None

Response Codes

204, 400, 500, 503

Role Permissions

Get Role Permissions

GET /roles/:role_name/scope/:scope_name/permissions
Request Body

None

Example Request
$ curl -X GET \
  https://us1.pusherplatform.io/services/chatkit_authorizer/v1/:instance_id/roles/:role_name/scope/:scope_name/permissions
Response Body

A list of all the permissions associated with the relevant role

Example

1
["room:create", "user:create"]
Response Codes

201, 400, 500, 503

Update Role Permissions

PUT /roles/:role_name/scope/:scope_name/permissions
Request Body

A JSON object with the following keys:

  • add_permissions (array|optional): The permissions that you want to add to the specified role (at the specified scope).
  • remove_permissions (array|optional): The permissions that you want to remove or revoke from the specified role (at the specified scope).

Note that atleast one of the two keys is required

See the available permissions list for a full list of permissions that you can provide for a role-scope combination.

Example Request
$ curl -X PUT \
  https://us1.pusherplatform.io/services/chatkit_authorizer/v1/:instance_id/roles/:role_name/scope/:scope_name/permissions \
  -d '{"add_permissions": ["room:typing_indicator:create", "room:update"], "remove_permissions": ["room:delete"]}'
Response Body

None

Response Codes

204, 400, 500, 503

Did you find this document useful?

We are always striving to create the most accurate and informative docs as possible. If there is something especially wrong (or right) here then please let us know.