Identity tools
Eleven tools describing you, the organizations you can act in and who changed what in one of them, and managing an organization’s invitations, roles and name. All eleven require a signed-in person; a machine credential is refused.
The write tools add no permission check of their own: each one calls the same kontrol mutation the
dashboard uses, and kontrol decides who may run it. A refusal comes back as an error block carrying
kontrol’s message, the role refusal (Unauthorized) and the seat-limit refusal included.
get_viewer
Section titled “get_viewer”Get the authenticated user’s profile and organization memberships. The agent chooses which organization to use.
Arguments: first defaults to 100. Pass after with the previous page’s endCursor to continue.
Returns: GraphQL JSON under viewer.user, containing id, email, name, image and an
organizations connection. Each edges[].node carries id, name, slug and viewerRole.
pageInfo carries endCursor and hasNextPage. A missing profile remains null.
list_organizations
Section titled “list_organizations”List all organizations the authenticated user belongs to.
Arguments: none.
Returns: an array of { id, name, slug, logo }, up to 100.
This is the tool that answers “which organization should I file into”. The id values it returns
are what every organization_id argument elsewhere expects.
get_organization
Section titled “get_organization”Get organization details by slug, including members.
Arguments:
| Name | Type | Required | Notes |
|---|---|---|---|
slug | string | yes | Organization slug (URL identifier), not the id. |
Returns: { id, name, slug, members } where members is an array of
{ id, name, email, role }, up to 100.
Returns an error block reading Organization "<slug>" not found if no organization matches, which
includes an organization that exists but you cannot see.
list_organization_audit_log
Section titled “list_organization_audit_log”List an organization’s audit log, newest first: the record of who changed what, the same entries the dashboard’s audit log page shows.
| Name | Type | Required | Notes |
|---|---|---|---|
organization_id | string | yes | |
first | number | no | Page size. Default 20, max 100. |
after | string | no | Cursor from a previous call’s pageInfo.endCursor. |
Returns: { totalCount, pageInfo, entries }. Each entry is
{ id, mutation, projectId, createdAt, changedBy, input, before, after }: the mutation that ran,
the project it touched (null for an organization-level change), when, who ran it as
{ id, name, email } (null when that account no longer resolves), the input it was called with,
and the record before and after it. input, before and after are returned as stored, unreshaped.
A plan without the audit log is refused by the Binclusive API, and its message comes back as an
error block. Returns an error block reading Organization "<id>" not found when no organization
matches.
list_organization_invites
Section titled “list_organization_invites”List an organization’s invitations with each one’s email, role, status and expiry.
Arguments:
| Name | Type | Required | Notes |
|---|---|---|---|
organization_id | string | yes | From list_organizations. |
first | number | no | Page size, default 20. |
after | string | no | endCursor from the previous page. |
Returns: { totalCount, pageInfo, invites } where invites is an array of
{ id, email, role, status, expiresAt }. status is one of pending, accepted, rejected,
canceled or expired; only a pending invite can be withdrawn. The id is what
withdraw_organization_invite takes.
Returns an error block reading Organization "<id>" not found if the id resolves to no organization.
invite_organization_member
Section titled “invite_organization_member”Invite a person to an organization by email. Requires the admin role in that organization.
Arguments:
| Name | Type | Required | Notes |
|---|---|---|---|
organization_id | string | yes | |
email | string | yes | Address the invitation goes to. |
role | admin | member | yes | Role the person joins with. |
Returns: the new invite, { id, email, role, status, expiresAt }.
When every seat on the organization’s plan is taken, kontrol refuses the invite and the error block
carries its message, followed by a line of JSON naming the code BILLING_SEAT_CAPACITY_EXHAUSTED and
the seat quota.
withdraw_organization_invite
Section titled “withdraw_organization_invite”Withdraw a pending invitation. Requires the admin role in the invite’s organization.
Arguments:
| Name | Type | Required | Notes |
|---|---|---|---|
invite_id | string | yes | From list_organization_invites. |
Returns: the withdrawn invite, { id, email, role, status, expiresAt }.
update_organization_member_role
Section titled “update_organization_member_role”Change a member’s role. Requires the admin role in that organization.
Arguments:
| Name | Type | Required | Notes |
|---|---|---|---|
organization_id | string | yes | |
member_id | string | yes | The membership id from get_organization’s members, not the person’s user id. |
role | owner | admin | member | yes | The new role. |
Returns: the membership, { id, role, user: { id, name, email } }.
A membership from another organization is refused with Member does not belong to this organization.
leave_organization
Section titled “leave_organization”Leave an organization you belong to.
Arguments:
| Name | Type | Required | Notes |
|---|---|---|---|
organization_id | string | yes |
Returns: a confirmation sentence, Left organization <id>.
When kontrol will not let you leave, for example because you are its only owner, the error block carries kontrol’s reason.
create_organization
Section titled “create_organization”Create a new organization with you as a member.
Arguments:
| Name | Type | Required | Notes |
|---|---|---|---|
name | string | yes | |
slug | string | yes | URL identifier. When it is taken, kontrol picks a free one close to it; it refuses only when every close one is taken. |
Returns: { id, name, slug }, with the slug the organization actually got.
update_organization
Section titled “update_organization”Rename an organization or change its slug. Requires the admin role in that organization. The logo is not changed here; upload it in the dashboard.
Arguments:
| Name | Type | Required | Notes |
|---|---|---|---|
organization_id | string | yes | |
name | string | no | New name. Left out, the name stays. |
slug | string | no | New slug. Left out, the slug stays. A slug already taken is refused. |
Returns: { id, name, slug }.