Accounts & access

Accounts, roles, members, project access, groups, object grants and custom roles: who can do what in Kortix.

An account holds projects and the people who work in them. Every person holds one account role, and a project role on each project they work in. This page is for the owners and admins who invite a team and decide who can do what.

kortix members invite alice@example.com --role member --project <project_id>:member

kortix access grant --user alice@example.com --agent kortix   # one person
kortix access grant --everyone --agent kortix                 # every project member

Owners and admins reach every project without a grant.

Accounts

Kortix creates a personal account when you sign up. You are its owner and its super-admin. Invite people to work in it with you.

• Several accounts, one login. One login can belong to many accounts. Each account keeps its own projects, members and settings.
• Switch. Open the project menu → Switch Project. It lists your projects grouped by account. In the CLI, kortix accounts use <slug|id> sets the account that account-scoped commands act on.
• Create a team account first. The account Kortix creates at sign-up is personal. It cannot hold SAML SSO (403 sso_personal_account), and a project cannot move to another account. For a team, select Create an account… before you create projects.
• Create another. Open the project menu → Switch Project → Create an account…. The creator becomes owner and super-admin. A self-hosted instance can restrict this to its server admin; the API then returns 403 account_creation_restricted. See Self-hosting.
• Rename. Account settings → Settings. Needs account.write.

kortix accounts ls          # the accounts you belong to
kortix accounts use         # pick the active account (interactive)
kortix accounts current     # print the active account
kortix accounts info        # one account in detail

Account settings

Open the project menu → Switch Project → Account settings.

Account roles

Each person holds exactly one account role: owner, admin or member.

• Members cannot create projects and cannot change billing. Owners and admins hold billing.write. Only an owner holds account.delete.
• Owners and admins are manager on every project in the account. This is a rule of the account role, not a grant, and a project grant cannot lower it. To limit an owner or admin on one project, change their account role to member first.
• Promotion removes project grants. When a person becomes owner or admin, Kortix deletes their direct project grants because the account role already covers every project.
• Only an owner touches owners. An admin who tries to remove an owner gets 403. Only an owner can grant the owner role or change an owner’s role.
• The last owner stays. Removing, demoting or leaving as the last owner returns 409. Make another member owner first.
• An account role belongs to a person. Binding owner, admin or member to a group returns 400. Give a group a project role or a custom role instead.

Opening another person’s private session is a separate, owner-controlled setting. See Who can open a session.

Who sees the member list

Owners and admins see every member and every group. A member sees nobody else:

• Members lists only themselves, not even the owners. kortix members does the same.
• They see no group, not even their own. Groups is hidden, kortix groups lists none, and reading any group answers 404.
• A project’s access list shows only themselves. A member who manages that project also sees the people and groups with access to it, so they can manage them, and still nobody without access.
• The Files share dialog names only themselves.
• Session costs list only their own sessions. Asking for another person’s costs answers 403, and another person’s session answers 404.
• In a project they do not manage, branches, change requests, the review inbox, gateway logs and spend show only their own work and the sessions they may open. Another member’s private session leaves no trace there.
• SSO group mappings list none.
• Usage by project lists only the projects they can read.
• API keys (GET /v1/accounts/tokens) list only their own keys and their sessions’ tokens. Only a caller with token.revoke lists every key in the account.
• Service accounts and OAuth clients answer 403: reading them needs token.create, the same leaf that creates them.

Another member’s access details (View access, GET .../iam/members/:userId/...) and the MFA enforcement preview stay with owners and admins. People you work with in a shared session or project still appear where their work does: as the author of a message, the owner of a session, or a person a secret is shared with.

To show the whole directory to more people, create a custom account role with member.read (every member) and group.read (every group), and assign it to those people or to a group. See Custom roles.

Members and invites

Invite people

1. Open Account settings → Members and select Invite.
2. Type one or more email addresses.
3. Pick the account role: Admin or Member.
4. For a member, optionally add projects and a project role for each.

What happens next depends on the address:

• The address has a Kortix login. Kortix adds the person at once, with the project roles you picked.
• The address has no login. Kortix emails an invite link. The invite is valid for 14 days. The project roles apply when the person accepts.

A self-hosted instance with no email provider confirms sign-ups without an email, so a password login does not prove its address there. Kortix adds such a login at once only when it is already a member of the account. Otherwise it creates an invite, and the login with that address accepts it from the project chooser or the Switch Project menu. That login is whoever signed up first with the address. See Unconfirmed email addresses.

Project roles in an invite apply to member invites only. Kortix ignores them on an admin invite, because an admin already reaches every project. To make someone owner, invite them as admin or member, then change their role.

Accept an invite

The invitee opens the link in the email and signs in or signs up with the invited address. Then they select accept or decline. Accept opens the first project the invite grants, or the account they joined.

In the mobile app, the project switcher lists pending invites under Invites. With no project to reopen, the app opens a pending invite first.

Manage invites and members

• Pending invites show on Members. Resending one sends the email again and starts a new 14-day window. Cancelling one revokes the link.
• Edit access in a member’s row menu changes their account role. To change several members at once, select their rows and select Change role.
• Remove from account removes the person’s role, project grants and group memberships. It revokes their personal access keys and the tokens of their running sessions at once. See When a person leaves.

When a person leaves

Removal, Leave and SCIM deactivation (active: false or DELETE, see SCIM provisioning) end the same things in the account, at once:

• the person’s roles, project grants and group memberships;
• their personal access keys and the tokens of their running sessions;
• their notifications and follows in the account’s projects;
• every computer account in the account that reaches a machine they own. This covers a computer they shared with a project and a computer they paired for themselves. The account becomes revoked, with metadata.revokedReason: owner_left. The computer stays theirs and keeps working in their other Kortix accounts;
• every reminder they set in the account’s projects. The reminder becomes paused. A reminder that a session’s agent set keeps firing;
• their seat on a per-seat plan. Their personal drive folders pass to an owner.

The audit log records one member.offboarded event, titled Offboarded a member, per departure. Its metadata holds reason (removed, left or deprovisioned), computers_revoked and reminders_disabled. A count is 0 when the person had nothing of that kind, and null when that step failed.

Errors

Members are unlimited and cost nothing extra. The account shares one credit wallet. See Plan changes.

Members from the CLI

kortix members ls
kortix members invite alice@example.com --role member --project <project_id>:manager
kortix members set-role alice@example.com --role admin
kortix members rm alice@example.com
kortix members invites ls
kortix members invites resend <invite_id>
kortix members invites cancel <invite_id>

--project <project_id>:<role> repeats, one per project. invite accepts admin or member. set-role accepts owner, admin or member.

Project access

A project has two roles.

A member cannot:

• edit the project, its settings or its sandbox, or delete it;
• read or change secrets, connectors, skills, models or workspace files;
• push or merge code, act on a change request, or delete a git ref;
• create, edit or delete triggers;
• manage access, gateway keys or budgets, or read usage;
• create, edit or deploy Apps;
• bind a session to a channel, or issue a project credential.

The API rejects editor with 400. It reads viewer and user as member. The exact permissions of each role are in Permissions.

Grant project access

1. Open Account settings → Projects and pick the project.
2. Select Grant access.
3. In Grant to, pick people or groups, or type an email to invite someone new.
4. Pick the Role.
5. Set Agents: All agents or Only these….
6. Optionally set Expires. The grant ends at that time.

Inviting an email address outside the account creates an account invite with the member role and this project role. A person who already has a login joins the account as member at once.

Access requests

A signed-in person who opens a project they cannot read sees Request access, with an optional note to the managers. Kortix notifies the project’s managers. One person can send 10 requests per hour, and one project receives at most 30 per hour.

A manager approves the request with a role (member by default) or rejects it. Approving grants the role at once.

Project access from the CLI

kortix access ls                                 # members and their project roles
kortix access invite bob@example.com --role member
kortix access grant <user_id> --role manager     # set a member's project role
kortix access revoke <user_id>                   # remove their project access
kortix access pending                            # pending project invites
kortix access resend <invite_id>                 # resend, new 14-day window
kortix access cancel <invite_id>
kortix access requests ls
kortix access requests approve <request_id> --role member
kortix access requests reject <request_id>

These commands act on the linked project, or on --project <project_id>. ls needs project.members.read. Every other command needs project.members.manage. invite and grant take --expires <iso>.

Groups

A group is a named set of people. Grant a role to a group, and every member of the group holds it. A group adds access. It never removes access a person already holds.

• Entitlement. Creating a group, renaming it and adding members need the Enterprise rbac entitlement. Without it the API returns 402 entitlement_required. Reading groups, removing members and deleting a group stay open, so an account can clean up after a plan change. Any other edit to a group, including its description, needs the entitlement.
• Delete. Deleting a group removes every grant it carried.
• Names. A group name is unique in the account. A duplicate returns 409.
• IdP-owned groups. A group that SCIM provisioned belongs to the identity provider. Renaming it or changing its members returns 409 group_idp_managed: change it in the IdP. Description edits and deletion stay allowed. See SCIM provisioning.

Give a group a project in Account settings → Projects → Grant access, or from the CLI:

kortix groups create Engineering --description "Everyone who ships code"
kortix groups add Engineering alice@example.com bob@example.com
kortix access grant --group <group_id> --role member --project <project_id>
kortix groups projects Engineering        # which projects it reaches, at which role
kortix groups members Engineering
kortix groups remove Engineering bob@example.com
kortix groups rm Engineering

Grant access to one object

Kortix has one grant record: an assignment. Every grant on this page is an assignment.

An object assignment carries no permission of its own. It narrows which objects a person reaches with the permissions their role gives. An agent, connector-account or secret grant uses the marker role agent-user. A Files folder grant uses folder-reader, folder-writer or folder-manager.

Agents

Agents are closed by default. A member reaches an agent only when a grant names them, one of their groups, or everyone in the project. A manager reaches every agent until the first grant names that agent. After the first grant, only the named principals reach it, managers included. Account owners and admins reach every agent.

Giving a person an agent also lets them use the secrets and connectors the agent declares. They use them through the agent; they cannot edit them.

Connector accounts and secret values

A shared connector account and a secret value are open to everyone in the project until their first grant. After the first grant, only the named people, groups and agents can use it. Removing the last grant opens it to the project again. Only a person can change these grants; an agent session gets 403.

• Connector accounts: Share accounts and give agents access.
• Secrets: Who can use it.

Everyone in the project

Pick Everyone in followed by the project name to give an agent or a connector account to every project member at once. This principal (project) holds object grants only, never a role. Each person keeps their own project role.

Object grants from the CLI

kortix access grant is the one command for object grants:

kortix access grant --user alice@example.com --agent support-bot
kortix access grant --group <group_id> --agent support-bot --expires 2026-12-31T00:00:00Z
kortix access grant --everyone --agent support-bot
kortix access grant --group <group_id> --connection <connection_id>
kortix access assignments                 # assignments on the linked project
kortix access assignments --all           # every assignment in the account
kortix access revoke <assignment_id>

kortix grants assign <agent> --to <email> writes the same agent grant.

The API route is POST /v1/accounts/:accountId/iam/assignments. The permission it needs follows what you grant:

Check why someone has access

• In the web app: open the member’s menu on Members and select View access. Without member.read, it opens only on your own row.
• Over the API: GET /v1/accounts/:accountId/iam/members/:userId/effective?action=project.secret.write&resourceType=project&resourceId=<project_id> returns allowed and a reason, such as project_role_insufficient or resource_scope_insufficient. POST .../effective:batch checks up to 64 actions in one call. Asking about yourself answers with your real credential; asking about someone else answers from their roles.

Per-feature access settings

Some features carry their own setting for one resource. Each narrows access. None grants a permission the role denies.

Agents have their own ceiling

A session runs with the agent’s permissions, not the permissions of the person who started it. Two limits apply: the role bound to the agent’s service account, and the agent’s kortix_permissions in kortix.yaml. Neither widens the other. See What an agent may do.

Custom roles

A custom role is a role your account defines from catalog permissions. It needs the Enterprise rbac entitlement: creating, editing or assigning one without it returns 402 entitlement_required.

• Only adds. A custom role grants permissions. Kortix has no deny rule.
• One scope. A role is account-scoped or project-scoped. It holds only permissions of its scope.
• No escalation. A custom role cannot hold a permission marked no under “Custom role” in Permissions. Owner and admin powers stay with the built-in roles.
• Key and name. The key is 2 to 64 characters of a-z, 0-9 and _. It never changes. The name is up to 128 characters.
• Delete. Deleting a custom role revokes every assignment of it.
• Built-in roles are fixed. Editing or deleting one returns 400.

Create and edit roles in Account settings → Roles, or from the CLI:

kortix roles create support_lead --name "Support lead" --scope project \
  --actions project.read,project.session.start,project.trigger.fire,project.members.manage
kortix roles set-actions support_lead --actions project.read,project.session.start
kortix roles edit support_lead --name "Support leads"
kortix roles show support_lead              # permissions and usage
kortix access grant --group <group_id> --role support_lead --project <project_id>
kortix roles rm support_lead

Built-in roles

kortix roles ls lists them with your custom roles. The folder roles are not in that list: a folder’s share dialog in Files sets them.

IAM as code

kortix roles export writes your custom roles and their bindings to TOML, or to JSON with --format json. kortix roles import <file> creates the roles that are missing, then imports the bindings. Bindings name roles by key, so a file moves between accounts.

kortix roles export --out roles.toml
kortix roles import roles.toml

kortix roles assign, unassign and assignments, and the /iam/policies routes, are a legacy API over the same assignments. They cover custom roles only. Use kortix access grant and /iam/assignments.

Super-admin

Super-admin is a flag on one membership, not a role. A super-admin passes every permission check in the account. Each request a super-admin makes is in the audit log like any other request.

• The person who creates an account starts as owner and super-admin.
• Only an owner grants or revokes it: kortix members super-admin <user> on|off, or PATCH /v1/accounts/:accountId/iam/members/:userId/super-admin.
• Demoting an owner clears their super-admin flag and records iam.member.super_admin.revoke.
• A super-admin is exempt from the account’s MFA requirement. SSO enforcement still applies. See Sign-in, SSO & API keys.

Branding

An account with the Enterprise branding entitlement replaces the Kortix marks its members see in the web app. Open Account settings → Branding.

• Formats. PNG, JPEG, WebP, SVG or ICO, up to 1 MiB each. Kortix rejects an SVG that carries script or other active content.
• Fallbacks. A missing logo uses the icon. A missing favicon uses the icon. A missing dark variant uses the dark icon, then the light image.
• Scope. Inside a project, members see the brand of the account that owns the project. The favicon follows the operating system’s color scheme; the other marks follow the app theme.
• Kortix stays. Sign-in pages, emails and public share pages stay Kortix-branded.
• Plan change. When the entitlement lapses, members see Kortix again. Nothing is deleted. Removing images and resetting stay available without the entitlement.

Writes need account.write and the entitlement (402 entitlement_required otherwise).

Audit log

The audit log records who did what in the account, when, through which credential, and whether it was allowed. Recording is always on. Reading, exporting and streaming the log need the Enterprise auditAccess entitlement.

What is recorded

Kortix writes one row for every request that reaches the API: HTTP requests, WebSocket upgrades, preview requests, git clones and pushes, and SCIM calls. A refused request is a row with outcome: denied. Events outside a request, such as a sandbox reading a secret or a background job expiring a grant, are rows too.

An agent’s row also names the person the agent acted for (on_behalf_of_user_id). Kortix derives the caller and the credential from what it authenticated, never from a request header. An anonymous request that names one of your projects is written with actor_type: anonymous.

Kortix does not record health probes, CORS preflights, or anonymous visitors to a deployed App.

Read the log

Open Account settings → Audit log. Reading needs audit.read (owners and admins) and the entitlement.

The Session filter searches the selected project’s sessions that you can open, by name or session-id prefix, on the server. It lists 20 matches at a time: Load more reads the next 20. To filter by any other session, paste its full session id into the search field and pick it. A pasted id works with no project selected, for a session you cannot open, and for a deleted session.

kortix audit ls --since 24h
kortix audit ls --outcome denied --since 7d
kortix audit ls --action iam. --json
kortix audit ls --credential-kind oauth_app --all
kortix audit project <project_id>
kortix audit session <session_id> --project <project_id>

The API route is GET /v1/accounts/:accountId/audit with the same filters as query parameters (actor_type, credential_kind, and so on).

• Project log: GET /v1/projects/:projectId/audit needs project.members.manage and the entitlement.
• Session timeline: GET /v1/projects/:projectId/sessions/:sessionId/audit needs project.session.read. Without the entitlement it returns only the unresolved pending approvals.

Who was active, and how often

The audit log names an identity, not a person. A sandbox, the CLI, or a script that holds a person’s token writes rows as that person, and those rows can outnumber the rows of what the person did in a browser by 100 to 1 or more. To ask “who used this project, and on which days”, read the activity rollup instead of counting log rows.

kortix audit activity --project <project_id> --since 6w
kortix audit activity --project <project_id> --since 6w --client browser
kortix audit activity --actor <user_id> --since 2026-09-01 --until 2026-09-30 --json

Each user gets one line: the days with activity, the distinct UTC hours with activity, the number of events, the last day, and one character per day (taller means more active hours).

The API route is GET /v1/accounts/:accountId/audit/activity, with since, until, project_id, actor, client, actor_type and credential_kind. It needs the same audit.read permission and entitlement as the log. A background job adds each closed 15-minute window of the log to the rollup about 2 hours after it closes. rolled_through in the response is the instant the counts reach. The rollup covers the last 90 days of the log.

Retention and export

kortix audit export --since 180d --format jsonl --out audit.jsonl
kortix audit export --action iam. --format csv --out iam.csv

Export takes the same filters, returns events oldest first, and reads the archive and the database as one list. Over the API: GET /v1/accounts/:accountId/audit/export?format=csv|jsonl, 10,000 events per page. Follow the X-Audit-Next-Cursor header until X-Audit-Complete is true.

Stream to a SIEM

An audit webhook POSTs every new event to your endpoint. Managing webhooks needs account.write. Creating, enabling or disabling one also needs the entitlement. Deleting one never does.

kortix audit webhooks add --name siem --url https://siem.example.com/kortix --action-prefix iam.
kortix audit webhooks ls
kortix audit webhooks disable <webhook_id>
kortix audit webhooks enable <webhook_id>
kortix audit webhooks rm <webhook_id>

add prints the signing secret (whsec_…) once, and sends a test event at once. --action-prefix limits delivery to matching actions. The URL must be http or https and must not resolve to a private address.

Each delivery is a POST with the body {"schema_version": 1, "event": {…}} and these headers:

Verify a delivery before you trust it:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody: string, header: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  return header.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}

A 2xx response within 5 seconds is a success. Kortix retries any other result up to 8 attempts, waiting 30 seconds and doubling up to 1 hour between attempts. After the last attempt the delivery is dead_letter. Read deliveries with GET /v1/accounts/:accountId/audit/webhooks/:webhookId/deliveries?status=<status>, and send one again with POST .../deliveries/:deliveryId/replay.

Action names

Every action is domain.resource.verb, and each API route has exactly one. Filter by prefix: iam. for access changes, git. for clones and pushes (git.clone, git.push; a push lists its refs in metadata.refs). A request that matched no route is api.route.unmatched. Audit actions lists every action and its title.

Permissions

A permission is one action, such as project.secret.write. Roles are sets of permissions. Read the live catalog with kortix permissions ls, filter with --scope account|project or --area <area>, and open one with kortix permissions show <action>. Over the API: GET /v1/accounts/:accountId/iam/permissions, which also returns each permission’s implies list.

Level is view, edit or admin.

Account permissions

Project permissions

Every project permission can go in a custom role.

project.credentials.issue is human-only. No role or grant gives it to an agent.

Leave or delete an account

Leave

Open Account settings → Members, open the menu on your own row, and select Leave account. You lose access to the account and its projects. Your computers stop serving the account, and your reminders in its projects pause. See When a person leaves. The last owner cannot leave (409): make another member owner first.

Delete

Deletion needs account.delete, which only an owner holds. It acts on your primary account: the first account you joined, normally the personal account Kortix created at sign-up. Open Settings → Profile and select Delete account. Pick one:

• Grace period. Kortix deletes the account 14 days later. You can cancel any time before then.
• Delete immediately. Kortix deletes the account at once. This cannot be undone.

Deletion removes:

• the account’s sandboxes, session files and Kortix-managed repositories;
• every project and session in the account, with its secrets and connector accounts;
• the subscription, which Kortix cancels, and the remaining credits;
• for your personal account, your login, your devices and your notifications.

The deletion routes are under /v1/account/ in the API reference.

To leave a team account you do not own, use Leave instead.