Managing permissions

Examplary uses a role-based and permission-based access control system to manage what users can do within an organization.

Roles and permissions can be managed through the Examplary web application or via the API.

Available roles

The following roles can be assigned to actors (users, groups, or organizations) on a resource:

Role	Description
`owner`	Full control over the resource, including the ability to delete it. Cannot be removed by other managers.
`manager`	Can edit the resource and manage its permissions (add/remove collaborators).
`editor`	Can edit the resource, but cannot manage permissions.
`viewer`	Read-only access to the resource.
`participant`	For students: can take an exam or access a practice space, but cannot edit or view settings.

Giving a user access to a content item

You can assign a permission by actor ID:

POST /permissions/exam_1234

{
  "actor": "user_5678",
  "role": "manager"
}

The actor field accepts a user_, group_, or org_ prefixed ID.

Alternatively, you can invite a user by email address instead of an actor ID. If the user does not yet exist in your workspace, they will be created automatically. Set sendInvite to true to send them an invitation email:

POST /permissions/exam_1234

{
  "email": "user@example.com",
  "role": "manager",
  "sendInvite": true
}

Listing permissions for a content item

GET /permissions/exam_1234

[
  {
    "actor": {
      "id": "user_5678",
      "name": "Jane Smith",
      "avatar": "https://cdn.examplary.ai/avatars/user_5678.jpg",
      "type": "user",
      "orgRole": "admin"
    },
    "role": "manager",
    "createdAt": "2024-01-15T12:34:56Z",
    "updatedAt": "2024-01-20T09:21:43Z",
    "createdBy": "user_9012"
  },
  {
    "actor": {
      "id": "group_9012",
      "name": "Teaching Staff",
      "type": "group"
    },
    "role": "viewer",
    "createdAt": "2024-01-15T12:34:56Z",
    "updatedAt": "2024-01-20T09:21:43Z",
    "createdBy": "user_9012"
  }
]

The actor object contains the following fields:

Field	Type	Description
`id`	string	The actor's ID (user, group, or org prefixed).
`name`	string	The actor's display name. May be absent if the actor could not be resolved.
`avatar`	string	URL to the actor's avatar image. Only present for users and orgs with a logo.
`type`	string	The type of actor: `"user"`, `"group"`, or `"org"`.
`orgRole`	string	The actor's role in the organization. Only present for `user` type actors.

Getting the role of a specific actor

GET /permissions/exam_1234/user_5678

{
  "actor": {
    "id": "user_5678",
    "name": "Jane Smith",
    "avatar": "https://cdn.examplary.ai/avatars/user_5678.jpg",
    "type": "user",
    "orgRole": "admin"
  },
  "role": "manager",
  "createdAt": "2024-01-15T12:34:56Z",
  "updatedAt": "2024-01-20T09:21:43Z",
  "createdBy": "user_9012"
}

Removing a permission

DELETE /permissions/exam_1234/user_5678

Returns { "success": true } on success.