Roles

Roles are named, reusable bundles of resource grants. Assign them to end users directly or pin them to groups; their grants are compiled into each member's effective access.

Role schema

List roles

get

/v1/roles

Returns all active roles in the account. Requires account owner or administrator access.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

List of roles.

application/json

A named, reusable bundle of resource grants. Roles are assigned to end users directly (_roleIds on the end-user record) or pinned to groups, and their grants are compiled into each member's effective access.

_idstring · objectIdRead-onlyRequired

Unique identifier for the role.

Example: 68c1d2e3f4a5b6c7d8e9f0a1

_userIdstring · objectIdRead-onlyOptional

Account owner's user id.

Example: 5f8d43a1b9e5a80011a35f2c

namestringRequired

Role name, unique within the account (case-insensitive).

Example: Finance tools

descriptionstringOptional

Free-text description of the role's purpose.

Example: Read access to finance MCP tools

createdAtstring · date-timeRead-onlyOptional

Timestamp when the role was created.

Example: 2026-07-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the role was last updated.

Example: 2026-08-15T14:30:15Z

204

No roles exist in the account.

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

get/v1/roles

GET /v1/roles HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "_id": "68c1d2e3f4a5b6c7d8e9f0a1",
    "_userId": "5f8d43a1b9e5a80011a35f2c",
    "name": "Finance tools",
    "description": "Read access to finance MCP tools",
    "resourceGrants": [
      {
        "resourceType": "mcpServer",
        "_resourceId": "6a1b2c3d4e5f6a7b8c9d0e1f",
        "capabilities": [
          "pset:6c3d4e5f6a7b8c9d0e1f2a3b"
        ]
      }
    ],
    "createdAt": "2026-07-01T09:15:32Z",
    "lastModified": "2026-08-15T14:30:15Z"
  }
]

Create a role

post

/v1/roles

Creates a role. Role names must be unique within the account (case-insensitive), and resourceGrants._resourceId values must reference resources owned by the same account. Requires account owner or administrator access.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

Writable fields for creating or replacing a role.

namestringRequired

Role name, unique within the account (case-insensitive).

Example: Finance tools

descriptionstringOptional

Free-text description of the role's purpose.

Example: Read access to finance MCP tools

Responses

201

Role created.

application/json

A named, reusable bundle of resource grants. Roles are assigned to end users directly (_roleIds on the end-user record) or pinned to groups, and their grants are compiled into each member's effective access.

_idstring · objectIdRead-onlyRequired

Unique identifier for the role.

Example: 68c1d2e3f4a5b6c7d8e9f0a1

_userIdstring · objectIdRead-onlyOptional

Account owner's user id.

Example: 5f8d43a1b9e5a80011a35f2c

namestringRequired

Role name, unique within the account (case-insensitive).

Example: Finance tools

descriptionstringOptional

Free-text description of the role's purpose.

Example: Read access to finance MCP tools

createdAtstring · date-timeRead-onlyOptional

Timestamp when the role was created.

Example: 2026-07-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the role was last updated.

Example: 2026-08-15T14:30:15Z

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

409

A role with this name already exists in the account.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

post/v1/roles

POST /v1/roles HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 211

{
  "name": "Finance tools",
  "description": "Read access to finance MCP tools",
  "resourceGrants": [
    {
      "resourceType": "mcpServer",
      "_resourceId": "6a1b2c3d4e5f6a7b8c9d0e1f",
      "capabilities": [
        "pset:6c3d4e5f6a7b8c9d0e1f2a3b"
      ]
    }
  ]
}

{
  "_id": "68c1d2e3f4a5b6c7d8e9f0a1",
  "_userId": "5f8d43a1b9e5a80011a35f2c",
  "name": "Finance tools",
  "description": "Read access to finance MCP tools",
  "resourceGrants": [
    {
      "resourceType": "mcpServer",
      "_resourceId": "6a1b2c3d4e5f6a7b8c9d0e1f",
      "capabilities": [
        "pset:6c3d4e5f6a7b8c9d0e1f2a3b"
      ]
    }
  ],
  "createdAt": "2026-07-01T09:15:32Z",
  "lastModified": "2026-07-01T09:15:32Z"
}

Get a role

get

/v1/roles/{_id}

Retrieves a single role by ID.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Role ID.

Responses

200

Role details.

application/json

A named, reusable bundle of resource grants. Roles are assigned to end users directly (_roleIds on the end-user record) or pinned to groups, and their grants are compiled into each member's effective access.

_idstring · objectIdRead-onlyRequired

Unique identifier for the role.

Example: 68c1d2e3f4a5b6c7d8e9f0a1

_userIdstring · objectIdRead-onlyOptional

Account owner's user id.

Example: 5f8d43a1b9e5a80011a35f2c

namestringRequired

Role name, unique within the account (case-insensitive).

Example: Finance tools

descriptionstringOptional

Free-text description of the role's purpose.

Example: Read access to finance MCP tools

createdAtstring · date-timeRead-onlyOptional

Timestamp when the role was created.

Example: 2026-07-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the role was last updated.

Example: 2026-08-15T14:30:15Z

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

get/v1/roles/{_id}

GET /v1/roles/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "_id": "68c1d2e3f4a5b6c7d8e9f0a1",
  "_userId": "5f8d43a1b9e5a80011a35f2c",
  "name": "Finance tools",
  "description": "Read access to finance MCP tools",
  "resourceGrants": [
    {
      "resourceType": "mcpServer",
      "_resourceId": "6a1b2c3d4e5f6a7b8c9d0e1f",
      "capabilities": [
        "tool:all"
      ]
    }
  ],
  "createdAt": "2026-07-01T09:15:32Z",
  "lastModified": "2026-08-15T14:30:15Z"
}

Update a role

put

/v1/roles/{_id}

Replaces the role's writable fields. Prefer resending the complete object — omitted fields are not preserved. Requires account owner or administrator access.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Role ID.

Body

Writable fields for creating or replacing a role.

namestringRequired

Role name, unique within the account (case-insensitive).

Example: Finance tools

descriptionstringOptional

Free-text description of the role's purpose.

Example: Read access to finance MCP tools

Responses

200

Updated role.

application/json

A named, reusable bundle of resource grants. Roles are assigned to end users directly (_roleIds on the end-user record) or pinned to groups, and their grants are compiled into each member's effective access.

_idstring · objectIdRead-onlyRequired

Unique identifier for the role.

Example: 68c1d2e3f4a5b6c7d8e9f0a1

_userIdstring · objectIdRead-onlyOptional

Account owner's user id.

Example: 5f8d43a1b9e5a80011a35f2c

namestringRequired

Role name, unique within the account (case-insensitive).

Example: Finance tools

descriptionstringOptional

Free-text description of the role's purpose.

Example: Read access to finance MCP tools

createdAtstring · date-timeRead-onlyOptional

Timestamp when the role was created.

Example: 2026-07-01T09:15:32Z

lastModifiedstring · date-timeRead-onlyOptional

Timestamp when the role was last updated.

Example: 2026-08-15T14:30:15Z

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

409

A role with this name already exists in the account.

application/json

422

Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.

application/json

put/v1/roles/{_id}

PUT /v1/roles/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 60

{
  "name": "Finance tools",
  "description": "Updated description"
}

{
  "_id": "68c1d2e3f4a5b6c7d8e9f0a1",
  "_userId": "5f8d43a1b9e5a80011a35f2c",
  "name": "Finance tools",
  "description": "Read access to finance MCP tools",
  "resourceGrants": [
    {
      "resourceType": "mcpServer",
      "_resourceId": "6a1b2c3d4e5f6a7b8c9d0e1f",
      "capabilities": [
        "tool:all"
      ]
    }
  ],
  "createdAt": "2026-07-01T09:15:32Z",
  "lastModified": "2026-08-15T14:30:15Z"
}

Delete a role

delete

/v1/roles/{_id}

Soft-deletes the role and removes it from the _roleIds of every group in the account. Requires account owner or administrator access.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

_idstring · objectIdRequired

Role ID.

Responses

204

Role deleted.

No content

400

Bad request. The server could not understand the request because of malformed syntax or invalid parameters.

application/json

401

Unauthorized. The request lacks a valid bearer token, or the provided token failed to authenticate.

Note: the 401 response is produced by the auth middleware before the request reaches the endpoint handler, so it does not follow the standard {errors: [...]} envelope. Instead the body is a bare {message: string} object with no code, no errors array. Callers handling 401s should key off the HTTP status and the message string, not try to destructure an errors[].

application/json

403

Forbidden. The authenticated caller does not have permission to perform this operation.

application/json

404

Not found. The requested resource does not exist or is not visible to the caller.

application/json

delete/v1/roles/{_id}

DELETE /v1/roles/{_id} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content