Skip to content

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 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 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 details by slug, including members.

Arguments:

NameTypeRequiredNotes
slugstringyesOrganization 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 an organization’s audit log, newest first: the record of who changed what, the same entries the dashboard’s audit log page shows.

NameTypeRequiredNotes
organization_idstringyes
firstnumbernoPage size. Default 20, max 100.
afterstringnoCursor 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 an organization’s invitations with each one’s email, role, status and expiry.

Arguments:

NameTypeRequiredNotes
organization_idstringyesFrom list_organizations.
firstnumbernoPage size, default 20.
afterstringnoendCursor 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 a person to an organization by email. Requires the admin role in that organization.

Arguments:

NameTypeRequiredNotes
organization_idstringyes
emailstringyesAddress the invitation goes to.
roleadmin | memberyesRole 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 a pending invitation. Requires the admin role in the invite’s organization.

Arguments:

NameTypeRequiredNotes
invite_idstringyesFrom list_organization_invites.

Returns: the withdrawn invite, { id, email, role, status, expiresAt }.

Change a member’s role. Requires the admin role in that organization.

Arguments:

NameTypeRequiredNotes
organization_idstringyes
member_idstringyesThe membership id from get_organization’s members, not the person’s user id.
roleowner | admin | memberyesThe 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 an organization you belong to.

Arguments:

NameTypeRequiredNotes
organization_idstringyes

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 a new organization with you as a member.

Arguments:

NameTypeRequiredNotes
namestringyes
slugstringyesURL 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.

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:

NameTypeRequiredNotes
organization_idstringyes
namestringnoNew name. Left out, the name stays.
slugstringnoNew slug. Left out, the slug stays. A slug already taken is refused.

Returns: { id, name, slug }.