Roles

Roles define what each team member can do in BenchKey. Every workspace has the four built-in roles, owner, admin, tech, viewer, and owners can define custom roles (Settings → Team & Access → Roles & Permissions) with their own permission matrix.

These read-only endpoints make the role catalog discoverable, so your integration never has to hardcode the builtins and guess at customs. The slug values are what you’ll see in the user object’s role field and what you can pass to the role list filter.

Assignability is narrower than the catalog. The app never assigns the owner role through team management, and the public change-role endpoint currently accepts only tech and viewer as targets. This resource is discovery, it tells you which slugs exist and which values you may encounter when reading users.

The role object

{
  "object": "role",
  "slug": "tech",
  "name": "Technician",
  "builtin": true,
  "description": null
}

Field	Type	Description
slug	string	Stable identifier accepted by the user role endpoints
name	string	Display label
builtin	boolean	true for the system roles (owner/admin/tech/viewer)
description	string|null	Owner-written description (custom roles)

---

List roles

GET /api/v1/roles

Returns every role a team member can hold in this workspace: the four built-in roles plus any custom roles the owner has defined, cursor-paginated in the app’s own display order.

Scope required: team.read

Query parameters

Parameter	Type	Description
limit	integer	Page size, 1–100 (default: 25)
cursor	string	Opaque cursor from a previous response’s next_cursor

curl

curl "https://app.benchkey.com/api/v1/roles" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Node.js

const res = await fetch("https://app.benchkey.com/api/v1/roles", {
  headers: { Authorization: "Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa" },
});
const { data } = await res.json();
const slugs = data.map((r) => r.slug); // ["owner", "admin", "tech", "viewer", "front-desk", ...]

Response

{
  "object": "list",
  "data": [
    { "object": "role", "slug": "owner",      "name": "Owner",      "builtin": true,  "description": null },
    { "object": "role", "slug": "admin",      "name": "Admin",      "builtin": true,  "description": null },
    { "object": "role", "slug": "tech",       "name": "Technician", "builtin": true,  "description": null },
    { "object": "role", "slug": "viewer",     "name": "Viewer",     "builtin": true,  "description": null },
    { "object": "role", "slug": "front-desk", "name": "Front Desk", "builtin": false, "description": "Check-in and checkout only" }
  ],
  "has_more": false,
  "next_cursor": null
}

See Pagination for how to page through results.

---

Retrieve a role

GET /api/v1/roles/:slug

Returns a single role by its slug (case-insensitive), e.g. tech or a custom slug.

Scope required: team.read

curl

curl "https://app.benchkey.com/api/v1/roles/front-desk" \
  -H "Authorization: Bearer bk_live_01J8X4_kvWz9nP3mRqTs7uYeBfGhDjLa"

Response

Returns the role object. Returns 404 if no role with that slug exists in this workspace.

---

Error codes

HTTP status	Code	Meaning
400	invalid_query	A query parameter was supplied as an array or object instead of a single scalar value
400	invalid_cursor	The pagination cursor is malformed
404	not_found	No role with that slug exists in this workspace
403	insufficient_scope	API key lacks team.read

See Errors for the full error envelope format.