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. Can only be removed or downgraded by another owner.
`manager`	Can edit the resource and manage its permissions (add/remove collaborators), but cannot grant the `owner` role, or remove or downgrade an existing owner's permission.
`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.

A resource can have multiple owners. To prevent it from ending up ownerless, an owner can never remove or downgrade their own owner permission — only another owner can do that for them. The same restriction applies when the owner role is granted to a group actor: only another owner can remove or downgrade that group's owner permission.

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",
    "inheritedFrom": {
      "object": "folder_3456",
      "type": "folder",
      "name": "Shared Resources",
      "role": "viewer"
    }
  }
]

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. Falls back to `"Unknown user"`, `"Unknown organization"`, or `"Unknown group"` 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.

When an item is inside a shared folder, the permissions list also includes actors who have access through that folder. These entries include an inheritedFrom field indicating the folder they inherited access from. Inherited permissions cannot be removed via DELETE /permissions/:resource/:actor — the call still returns { "success": true }, but the actor keeps their access since there is no direct grant on the item to revoke. To revoke inherited access, update the permissions on the folder itself.

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"
}

Use me instead of an actor ID (GET /permissions/exam_1234/me) to get the authenticated user's own role on a resource.

Removing a permission

DELETE /permissions/exam_1234/user_5678

Returns { "success": true } on success.