End Users
End users are people who consume an account's MCP servers without getting workspace access — they sign in through MCP OAuth, optionally via an external IdP. Use these endpoints to invite end users (singly or in bulk), list and revoke them, and inspect the effective MCP tool access compiled from their grants, groups, and roles.
End user schema
Returns the account's end users with identity fields (email, name, lastSignIn) joined from each user record, plus a computed hasWorkspaceShare flag indicating whether the same person also holds a workspace access record. Requires account owner or administrator access.
Return only end users created by the given provisioning source.
List of end users.
An end user's access record in the account. End users authenticate through
MCP OAuth (optionally via an external IdP) to use MCP servers; they do not
get workspace access. The _id is the access-record id, not the user's own
id — the user's identity is in _sharedWithUserId.
Access-record id for this end user in the account.
68b1c2d3e4f5a6b7c8d9e0f1Account owner's user id.
5f8d43a1b9e5a80011a35f2cThe end user's own user id.
624774a6a7574d3ed9f9a5ccDistinguishes end-user access records from workspace access records.
How this end-user record was created.
When true, the end user has completed invite setup (or was JIT-provisioned).
When true, the end user has declined the invitation.
When true, the end user's access is suspended without deleting the record.
Roles assigned directly to this end user.
Email address of the end user, joined from the user record.
enduser@example.comDisplay name of the end user, joined from the user record.
Ana EnduserWhen the end user last signed in. Null when they have never signed in.
2026-08-02T17:02:59.370ZWhen true, the same person also has an active workspace access record on this account.
Timestamp when the end-user record was created.
2026-07-01T09:15:32ZTimestamp when the end-user record was last updated.
2026-08-15T14:30:15ZBad request. The server could not understand the request because of malformed syntax or invalid parameters.
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[].
Forbidden. The authenticated caller does not have permission to perform this operation.
GET /v1/endusers HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"_id": "68b1c2d3e4f5a6b7c8d9e0f1",
"_userId": "5f8d43a1b9e5a80011a35f2c",
"_sharedWithUserId": "624774a6a7574d3ed9f9a5cc",
"userType": "end-user",
"provisionedBy": "invite",
"accepted": true,
"dismissed": false,
"disabled": false,
"groupMemberships": [
{
"_groupId": "68a1b2c3d4e5f6a7b8c9d0e1",
"source": "manual"
}
],
"resourceGrants": [
{
"resourceType": "mcpServer",
"_resourceId": "6a1b2c3d4e5f6a7b8c9d0e1f",
"capabilities": [
"tool:all"
]
}
],
"_roleIds": [],
"email": "enduser@example.com",
"name": "Ana Enduser",
"lastSignIn": "2026-08-02T17:02:59.370Z",
"hasWorkspaceShare": false,
"createdAt": "2026-07-01T09:15:32Z",
"lastModified": "2026-08-15T14:30:15Z"
}
]Finds or creates the user by email, creates an end-user access record, applies the requested group memberships and direct grants, and sends an invite email. Account owners cannot be invited as end users. Requires account owner or administrator access.
Invitation details for a single end user.
Email address to invite. Normalized to lowercase and trimmed.
enduser@example.comDisplay name for the invited user. Defaults to the email local-part when omitted.
Ana EnduserGroups to add the end user to as manual memberships.
End user invited.
Result of a successful single invite.
Account owner's user id.
5f8d43a1b9e5a80011a35f2cAccess-record id of the newly created end user.
68b1c2d3e4f5a6b7c8d9e0f1Outcome of the invite.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
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[].
Forbidden. The authenticated caller does not have permission to perform this operation.
An end-user record already exists for this user in the account.
Error code: enduser_ashare_exists.
Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
POST /v1/endusers/invite HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 31
{
"email": "enduser@example.com"
}{
"_userId": "5f8d43a1b9e5a80011a35f2c",
"_ashareId": "68b1c2d3e4f5a6b7c8d9e0f1",
"status": "invited"
}Invites 1–100 end users in one request, applying the same optional groupIds and directGrants to every invite. Processing is sequential and partial-success: a failed item never aborts the batch, so the response is HTTP 200 with a per-email result even when some items fail. Only top-level structural errors (missing or non-array emails, more than 100 emails, non-array groupIds/directGrants) return 400. Requires account owner or administrator access.
Batch invitation for up to 100 end users. The optional groupIds and
directGrants are shared and applied identically to every invite in
the batch.
Email addresses to invite. Normalized to lowercase, trimmed, and de-duplicated within the batch.
Groups added as manual memberships on every created end-user record.
Batch processed, including partial success. One result per input email.
Batch outcome with one result per input email, in input order. Processing is partial-success — a failed item never aborts the batch.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
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[].
Forbidden. The authenticated caller does not have permission to perform this operation.
POST /v1/endusers/invite/bulk HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 84
{
"emails": [
"a@example.com",
"b@example.com"
],
"groupIds": [
"68a1b2c3d4e5f6a7b8c9d0e1"
]
}{
"summary": {
"total": 2,
"invited": 1,
"failed": 1,
"skipped": 0
},
"results": [
{
"email": "a@example.com",
"status": "invited",
"_userId": "5f8d43a1b9e5a80011a35f2c",
"_ashareId": "68b1c2d3e4f5a6b7c8d9e0f1"
},
{
"email": "b@example.com",
"status": "failed",
"code": "enduser_ashare_exists"
}
]
}Soft-deletes the end-user access record and clears its group memberships. Any workspace access record the same person holds is unaffected. Requires account owner or administrator access.
End-user access-record id (from the end users list).
End user revoked.
No content
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
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[].
Forbidden. The authenticated caller does not have permission to perform this operation.
Not found. The requested resource does not exist or is not visible to the caller.
DELETE /v1/endusers/{_ashareId} HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Compiles the end user's effective MCP server tool access with source attribution — the union of direct grants, group grants, role grants, and permission sets. The result is recomputed on every request rather than cached. Requires account owner or administrator access.
End-user access-record id (from the end users list).
Compiled effective access with attribution.
The compiled MCP access for one end user, with source attribution. Access is the union of the end user's direct grants, group grants, role grants (direct or via groups), and permission sets on the target servers, recompiled on every request.
End-user access-record id this compilation applies to.
68b1c2d3e4f5a6b7c8d9e0f1The end user's own user id.
624774a6a7574d3ed9f9a5ccType of the access record the compilation was run for.
How the end-user record was created.
Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
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[].
Forbidden. The authenticated caller does not have permission to perform this operation.
Not found. The requested resource does not exist or is not visible to the caller.
GET /v1/endusers/{_ashareId}/effective-access HTTP/1.1
Host: api.integrator.io
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"_ashareId": "68b1c2d3e4f5a6b7c8d9e0f1",
"_userId": "624774a6a7574d3ed9f9a5cc",
"userType": "end-user",
"provisionedBy": "invite",
"groups": [
{
"_id": "68a1b2c3d4e5f6a7b8c9d0e1",
"name": "Finance",
"source": "manual"
}
],
"roles": [
{
"_id": "68c1d2e3f4a5b6c7d8e9f0a1",
"name": "Finance tools",
"via": [
"group:Finance"
]
}
],
"access": [
{
"resourceType": "mcpServer",
"_resourceId": "6a1b2c3d4e5f6a7b8c9d0e1f",
"resourceName": "Finance MCP",
"tools": [
{
"_id": "6b2c3d4e5f6a7b8c9d0e1f2a",
"name": "lookup-invoice",
"via": [
"role:Finance tools (group:Finance)"
]
}
],
"deniedTools": []
}
]
}Last updated
Was this helpful?