> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentmark.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Users and access control
> Roles, permissions, custom roles, app-level access, and team management
AgentMark uses a role-based access control (RBAC) system with granular permissions at the organization and app level.
## Built-in roles
Every organization member holds one of these roles:
| Role | Access |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner** | Full access, including billing and subscription management. Assigned to the org creator. Only Owners can promote other members to Owner. |
| **Admin** | Full access to all org resources, settings, and member management. Read-only billing: only Owners can change the subscription plan or payment method. |
| **Write** | Create and edit prompts and datasets; create and view API keys; run experiments; view traces. Read-only on apps: only Admins and Owners can create or delete apps. Can't manage members or billing. |
| **Read** | Read-only access to all org resources. Can't create, edit, or delete anything. |
## Inviting members
Invite team members from **Settings → Members** in the AgentMark Dashboard. AgentMark sends invitations by email, and they expire after 7 days. Each invitation includes a role assignment.
## Custom roles and app-level access
**Team tier and above.** Custom roles and app-level role assignments require a Team or Enterprise subscription.
### Custom roles
Create custom roles with cherry-picked permissions for fine-grained access control:
1. Navigate to **Settings → Roles** in the Dashboard
2. Click **Create role**
3. Name the role and select the specific permissions to grant
4. Assign the role to members
Custom roles draw from the full permission catalog, so you can grant access to specific features (for example, "can view traces and run experiments but can't edit prompts or manage billing").
### App-level roles
Assign different roles per app within the same organization. A member might have **Write** access to your staging app but **Read** access to production.
To configure per-app access, open **Settings → Members** in the AgentMark Dashboard, click the row action menu next to a member, and choose **Manage app access**. From the dialog, toggle each app on or off and set a built-in or custom role per app.
## API keys
Each API key covers an app **and an environment**. You create the key in the environment selected in the breadcrumb, and it grants access only to that environment's resources (prompts, traces, experiments); a `prod` key can't reach `staging` data.
* Create and manage keys from the app-level **Settings → API keys** page in the Dashboard (under `/orgs//apps//settings/api-keys`); the list shows only the breadcrumb-selected environment's keys
* Keys are rate-limited by tier (see [Billing and usage](/deploy/billing-and-usage) for limits)
* Key names must be unique within an app
For a step-by-step Dashboard walkthrough with screenshots, see [API keys](/deploy/api-keys).
### Role presets
Each API key carries either a preset role or a custom permission set. When you create or edit a key, choose one of these presets or select **Custom** to toggle individual permissions.
| Role | Access |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SDK** | `trace.write`, `template.read`, `score.write`. CLI and SDK integrations that ingest traces, read templates, and write scores. |
| **Read-Only** | `trace.read`, `span.read`, `session.read`, `score.read`, `score_config.read`, `dataset.read`, `metrics.read`, `deployment.read`, `environment.read`, `alert.read`, `slack_integration.read`, `app.read`. Dashboards and BI tools: read-only access to all data. |
| **Full Access** | Every permission in the catalog. Admin and CI pipelines. |
| **Custom** | Toggle individual permissions. Select at least one. |
### Permission catalog
The custom permission picker exposes these permissions, grouped by resource:
| Permission | Description |
| ------------------------ | ------------------------------------------------- |
| `trace.write` | Ingest new traces via `POST /v1/traces` |
| `trace.read` | Read traces and graph views |
| `span.read` | Read spans via `GET /v1/spans` |
| `session.read` | Read sessions |
| `template.read` | Read prompt templates |
| `score.read` | Read scores, aggregations, and score names |
| `score.write` | Create scores |
| `score.delete` | Delete scores |
| `score_config.read` | Read score configs |
| `dataset.read` | Read datasets |
| `dataset.write` | Create dataset rows |
| `metrics.read` | Read aggregate metrics |
| `experiment.read` | Read experiments, runs, and prompt execution logs |
| `api_key.read` | Read API keys |
| `api_key.insert` | Create API keys |
| `api_key.delete` | Delete API keys |
| `deployment.read` | Read deployments |
| `environment.read` | Read environments |
| `environment.insert` | Create environments |
| `environment.update` | Update environments |
| `environment.delete` | Delete environments |
| `environment.promote` | Promote / roll back environments |
| `alert.read` | Read alerts |
| `alert.insert` | Create alerts |
| `alert.update` | Update alerts |
| `alert.delete` | Delete alerts |
| `slack_integration.read` | Read Slack channels |
| `app.read` | Read apps |
See [Endpoint permissions](/api-reference/authentication#endpoint-permissions) for the full mapping of API endpoints to permissions.
When a key attempts an operation it doesn't have permission for, the API returns `403 Forbidden`.
### Creating a scoped key
1. Navigate to the app's **Settings → API keys** page in the Dashboard
2. Click **Create API key**
3. Enter a name for the key
4. Select a **role** or choose **Custom** to toggle individual permissions
5. Click **Create**, then copy the key immediately, as it's only shown once
### Editing key permissions
You can change an existing key's permissions at any time:
1. Open the app's **Settings → API keys** page
2. Click the pencil icon next to the key you want to modify
3. Update the role or individual permissions
4. Save your changes; the key value stays the same
## Access-control audit trail
AgentMark records every access-control change in your organization in an immutable audit log:
* **Membership lifecycle**: invites sent, resent, and accepted; role changes; member removals
* **Custom roles**: created, updated, deleted, assigned, and unassigned
* **App-level roles**: granted, changed, revoked, and app-scoping toggles
* **API keys**: created, permission edits with before and after state, and deletions. AgentMark never records key material, only the grant surface.
Each entry captures who made the change, when, from where (IP address and client), the target (member email, role name, or key name), and the before and after state. AgentMark also records denied attempts to make access-control changes. Changes made by AgentMark support at your request appear in your trail with the acting support engineer identified. Entries are write-once and tamper-evident: nobody, including organization owners, can edit or delete them, and a verifiable hash chain links every entry to the one before it.
Recording is always on for every organization, so your trail exists from day one and upgrading reveals your full history.
### Viewing and exporting the audit log
**Enterprise tier.** Viewing and exporting the audit log requires an Enterprise subscription. Recording stays on for every plan.
Open **Settings → Audit log** in the Dashboard to browse your organization's trail. Owners and Admins see the tab by default. To give other members access, create a custom role with the **View the organization audit log** permission. Filter entries by action, target, or date range, and click any row for full detail, including the request context and the before and after state.
Click **Export CSV** on the same page for the full trail as a spreadsheet-safe CSV with UTC timestamps, ready for your SIEM or compliance evidence collection.
### Retention
AgentMark retains audit entries, including request context, for the lifetime of your organization. Configurable retention windows are on the roadmap for Enterprise; contact [support](mailto:hello@agentmark.co) if your compliance program needs a specific schedule.
## SSO
**Team tier and above.** SAML 2.0 SSO requires a Team or Enterprise subscription.
Configure SAML 2.0 single sign-on for your organization:
* **Supported providers**: Azure AD, Okta, Google Workspace, and any SAML 2.0-compliant IdP
* **Domain allowlisting**: restrict sign-in to specific email domains
* **Enforcement mode**: require SSO for all org members, who must authenticate through your identity provider with no password fallback
* **Attribute mapping**: map IdP attributes (full name, first/last name) to AgentMark profiles
To configure SSO, navigate to **Settings → SSO** in the AgentMark Dashboard.
Have questions?
Reach out any time: