import { Callout } from 'nextra/components'

Access Control, Roles & Teams

DocsGPT has two independent permission planes:

• Global RBAC — every user holds the admin or user role for the whole instance. Admins can manage other users and see instance-wide usage and audit data.
• Team roles — within a team a user is a team_admin or team_member, and resources can be shared to teams or individual members.

The two planes never mix: a global admin is a superuser over all teams, but a team_admin is not a global admin.

Global roles (RBAC)

To see the roles the current request resolves to, call:

GET /api/user/me   →   { "user_id": "...", "roles": ["user"], "email": "...", "name": "...", "picture": "..." }

This is the canonical way to check a caller's effective roles (distinct from /api/config, which only reports the instance auth_type).

Granting admin

There are four ways an account becomes an admin:

1. The grant_admin script — run python scripts/grant_admin.py <user_id> on the server to grant (or --revoke / --list) the admin role directly. This is the canonical bootstrap for the first admin.
2. OIDC group mapping — OIDC_ADMIN_GROUPS auto-grants admin to members of the listed IdP groups. See below.
3. Local no-auth mode — LOCAL_MODE_ADMIN=true grants admin when AUTH_TYPE=None (self-host, no authentication).
4. Grant by an existing admin — through the admin API/dashboard.

Bootstrapping the first admin

Granting admin through the dashboard itself requires already being an admin, which creates a chicken-and-egg problem on a fresh deployment. Break it one of these ways:

• Run the script on the server: python scripts/grant_admin.py <user_id> (the user_id is the OIDC sub). The grant is written to user_roles with source='manual' and takes effect on the user's next request. Use --list to see current admins and --revoke to remove a manual grant.
• Set OIDC_ADMIN_GROUPS to a group you belong to, and sign in — you become an admin automatically.
• For a no-auth local install, use LOCAL_MODE_ADMIN=true.

Admin via OIDC groups

When OIDC_ADMIN_GROUPS is set, group membership is mapped to the admin role at every sign-in and every silent renewal — so removing a user from the admin group revokes their admin at the next renewal, just like the sign-in allowlist. It is independent of OIDC_ALLOWED_GROUPS (which controls whether a user may sign in at all). Leaving OIDC_ADMIN_GROUPS unset never mass-revokes admin.

OIDC_ADMIN_GROUPS=platform-admins
# OIDC_GROUPS_CLAIM=groups   # only if your IdP uses a different claim name

If your IdP only exposes groups via the userinfo endpoint, DocsGPT backfills them from there during reconciliation, the same as the allowlist.

Admin dashboard

Admins get a dashboard backed by a REST surface under /api/admin (every endpoint requires the admin role). All mutating actions are written to the auth_events audit log with the acting admin recorded in the metadata.

Teams

Teams let a group of users collaborate and share resources. Teams are self-serve — any user can create one and manage its membership.

Team roles

The team owner is a distinct concept from team_admin: ownership can be transferred, and a global admin is treated as a superuser over every team.

Managing a team

Membership and removal are guarded so a team can never be left without an admin (the last-admin guard).

Sharing resources with a team

Four resource types can be shared: agents, sources, prompts, and tools. Sharing is additive — it grants access to others without changing ownership.

Sharing rules:

• Only the owner of a resource can share it.
• A share targets either the whole team or a single member.
• Each share carries an access level: viewer (read-only) or editor (read and modify).
• editor is not the same as owner — an editor can change a resource but cannot delete it or re-share it.
• Shared tools run server-side with the owner's credentials; a grantee never sees the owner's secrets.

Audit log

Access-control actions are appended to the auth_events table alongside the authentication events. This includes admin actions — admin_user_activated / admin_user_deactivated, admin_sessions_revoked, role_granted / role_revoked (with metadata.source = manual or oidc_group) — and team events (team.create, team.member_add, team.member_role, team.member_remove, team.share, team.unshare, team.transfer_owner, team.delete). The acting admin is recorded in the event metadata.

Related

• SSO with OIDC — sign-in, group allowlists, and the auth_events table.
• App Configuration — the full settings reference.