# Roles and permissions

> The twelve permissions, the built-in admin, auditor and member roles, custom roles, and how permissions apply to API keys.

Product: AI Cost Optimizer Gateway (ACOG). Web version: https://tessarac.com/docs/acog/reference/roles-and-permissions. Last updated: 2026-10-16.

Everything a person or an API key can do in ACOG is governed by one set of permissions. Roles are named sets of permissions; an API key's scopes are permissions too.

## Permissions

| Permission | Console label | Allows |
|---|---|---|
| `proxy` | Gateway access | Send AI requests through the gateway |
| `read:metrics` | Dashboards | View usage and savings dashboards |
| `read:billing` | Billing | View invoices and billing status; view governance settings and the audit log |
| `admin:users` | Team & roles | Invite, remove and manage members and roles |
| `admin:keys` | API keys | Create and revoke API keys for anyone in the organization; manage applications |
| `admin:providers` | Provider connections | Connect and disconnect AI provider accounts; cost policies |
| `admin:sso` | Single sign-on | Configure single sign-on identity providers |
| `admin:teams` | Teams | Create teams and manage their membership |
| `admin:budgets` | Budgets & limits | Set budgets, rate limits, model access and guardrails |
| `admin:security` | Data loss prevention | Manage data loss prevention rules, connect source code, change prompt security |
| `audit:conversations` | Activity | See every request made through the gateway and by whom, including stored conversations |
| `admin:org` | Organization profile | Edit the organization's profile, gateway settings, webhooks and observability |

## Built-in roles

| Role | Permissions |
|---|---|
| **Admin** | All twelve |
| **Auditor** | `read:metrics`, `read:billing` |
| **Member** | `read:metrics`, `proxy` |

Built-in roles cannot be edited. An organization always has at least one admin.

## Custom roles

Under **Admin → Users → Roles**, create a role from any combination of permissions, except `audit:conversations`. A custom role cannot be deleted while members hold it.

## Granting is bounded

You can give a role, or create a key, only with permissions you hold yourself. A refused grant returns `403` naming the permission you lack.

## API keys

A key's scopes are permissions, `proxy` by default. A key never has more permissions than its creator, and `audit:conversations` is never available to a key: reading other people's conversations requires a person signed in to the console.

## Single sign-on

People who sign in through single sign-on get a role from your identity provider's groups. See [Single sign-on](https://tessarac.com/docs/acog/administer/single-sign-on.md#3-map-groups-to-roles).