Teams & roles (RBAC)
Invite team members and set roles, understand the owner/admin/member/viewer permission matrix, and read the org audit log and its content-hashed artifacts.
An Algenta organization has members, each with one role, and every privileged action is gated by that role. This page covers inviting and managing members, the exact capabilities each role grants, and how to read the audit log — including the tamper-evident, content-hashed artifact records.
Roles are ordered highest to lowest: owner → admin → member → viewer. A role grants everything below it, so an owner can do anything an admin can, and so on.
Invite and manage members
Invite a member
Send an invite with an email and a role. Valid roles are owner, admin, member, and viewer; role defaults to member if omitted.
curl -sS -X POST "https://api.algenta.ai/v1/team/invite" \
-H "Authorization: Bearer $ALGENTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "teammate@example.com", "role": "member" }'The 201 response returns the invite_id along with the invite's email, role, status, and expires_at. An unknown role is rejected with 422 invalid_role.
List the team
Read the current members. Pass page and limit for a paginated envelope; omit both to get a plain array.
curl -sS "https://api.algenta.ai/v1/team?page=1&limit=25" \
-H "Authorization: Bearer $ALGENTA_API_KEY"Each member carries user_id, name, email, role, and status (for example active or suspended).
Change a role or remove a member
Update a member's role, or remove them from the org.
curl -sS -X PATCH "https://api.algenta.ai/v1/team/$USER_ID/role" \
-H "Authorization: Bearer $ALGENTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "role": "admin" }'curl -sS -X DELETE "https://api.algenta.ai/v1/team/$USER_ID" \
-H "Authorization: Bearer $ALGENTA_API_KEY"Removing a member returns 204. Removal suspends the member (it never deletes them) and, in the same step, revokes their API keys, revokes the devices registered under those keys, revokes pending invitations they sent or that are addressed to them, and stops any GitHub App installation they connected from admitting GitHub organization admins until an admin connects it again. Removing a member who is already suspended — for example by a seat downgrade, which revokes the same things — succeeds and revokes anything they still held. A seat downgrade suspends only the members beyond the seats the organization pays for (owners and the longest-standing members keep theirs); renewals and billing updates within those seats suspend nobody. Re-inviting a removed member reactivates them once they accept, but their old API keys stay revoked — they mint new ones.
Changing a member's role to member or viewer also stops any GitHub App installation they connected from admitting GitHub organization admins until an admin connects it again. A member's GitHub identity never acts above their role: signing in with another account linked to the same GitHub identity gives no more access than the member's own seat. This holds for every GitHub identity the member has signed in with, not only the first, and a removed member gets no access through any of them.
Several guardrails protect the org:
You cannot change your own role (
403self_role_change_forbidden).Only an owner may grant the
ownerrole (403owner_grant_forbidden).The last active owner cannot be demoted or removed (
409last_owner), so an org can never end up ownerless.Accepting an invitation needs the invitee's own signed-in session with a confirmed email equal to the invited address, and the inviter must still be able to grant it (
409invite_inviter_inactive). An invitation sent before a member's removal never reactivates them (409invite_predates_removal).Team changes that race each other are serialized; if one still loses a database race it returns
409team_update_conflictwithdetails.retryable: true— retry it.
Role permission matrix
Each role grants a superset of the roles beneath it. The table below shows where each capability's minimum role sits.
Run simulations, queries, and reads
yes
yes
yes
yes
Manage your own API keys
no
yes
yes
yes
Revoke another member's API key
no
no
yes
yes
Revoke a service key (e.g. the GitHub App's)
no
no
no
yes
Invite / remove members, change roles
no
no
yes
yes
View audit logs and egress policy
no
no
yes
yes
View deployment cost
no
no
yes
yes
Activate a server deployment license
no
no
yes
yes
Move a deployment to a different deployment key
no
no
no
yes
Request / deprovision a deployment
no
no
no
yes
Grant the owner role
no
no
no
yes
Billing checkout and portal
no
no
no
yes¹
¹ In an organization created by a GitHub App install that has no active owner, a verified admin of the installed GitHub organization may also check out and open the billing portal; GitHub is asked again on every such request.
When a call is made below the required role, the API returns 403 with the required and current roles in the error details. Role-gated changes always check the caller's role as it is now, not as it was cached when their key was last used. Only a member's own credential passes a role check: a device license token is refused (403 license_principal_not_permitted), and only a member's own API key can manage the team (403 team_actor_not_permitted).
Issuing a credential — registering a device, heartbeating or renewing its license, activating a deployment, or creating an API key — also re-checks the key and its member in the database first, so a removed member is refused (401) by every API server at once, and a credential created while the member is being removed is revoked with the rest. Requests that pass no role gate and issue no credential — reads, and writes such as changing the execution policy or a connector — can lag a removal, role change or key revocation briefly on another API server: up to 30 seconds for an API key that server had cached (the server that handled the change refuses at once). A website session's verified identity facts can lag up to the session token's expiry (at most 1 hour), and a confirmed GitHub organization admin up to 60 seconds (every mutation re-asks GitHub). A device license is checked against the device registry on every request (cached up to 30 seconds per API server): once its device, its API key or its member is revoked or removed it is refused with 401 license_revoked, and while its organization is suspended it is refused with 403 organization_suspended, as the organization's API keys are.
Read the audit log
Every privileged action is recorded. Two endpoints expose it: the live database log and the immutable, content-hashed artifact store. Both require the admin role and return the same paginated AuditLogResponse shape.
Both endpoints accept the same filters — actor_email, action, resource_type, result (success or failure), plus lineage filters policy_snapshot_id, schema_snapshot_id, manifest_version, and request_hash — with page (default 1) and limit (default 25, max 100).
Next steps
Last updated
Was this helpful?