Skip to main content
API keys authenticate every request to the AgentMark Gateway. Each key is scoped to a single app and carries either a preset role (SDK, Read-Only, Full Access) or a custom permission set you assemble yourself. The gateway checks a key’s permissions on every request and returns 403 Forbidden when a key lacks the required permission. For the header format and the full endpoint-to-permission mapping, see Authentication. For the permission catalog and role definitions, see Users & Access Control.

​
Locate the API Keys settings

Open the AgentMark dashboard, switch to the app you want to scope the key to (the app shown in the breadcrumb at the top), then navigate to Settings > API Keys. Settings > API Keys page with empty state and a Create API Key button
Keys are scoped to the app shown in the breadcrumb. A key created here cannot access any other app’s traces, templates, or datasets.

​
Create an API key

  1. Click Create API Key.
  2. Enter a Name (used for identification in the list; must be unique within the app).
  3. Select a Role or choose Custom to pick permissions individually.
  4. Click Create.

​
Role presets

Three presets cover the common integration patterns: SDK — trace.ingest, template.read, score.write. CLI and SDK integrations: ingest traces, read templates, write scores. Create API Key modal with the SDK role selected, showing trace.ingest, template.read, and score.write permission chips Read-Only — trace.read, span.read, session.read, score.read, dataset.read, metrics.read. Dashboard and BI tools: read-only access to all data. Create API Key modal with the Read-Only role selected, showing read-only permission chips across traces, spans, sessions, scores, datasets, and metrics Full Access — every permission in the catalog. Admin and CI pipelines; grant only when needed.

​
Custom permissions

Select Custom to build a permission set from scratch. Permissions are grouped by resource (Traces, Templates, Scores, Spans, Sessions, Datasets, Metrics, Experiments) so you can mix and match — for example, trace.read + score.write for a scoring worker, or dataset.write only for a CI job that uploads eval rows. Create API Key modal with Custom role expanded, showing grouped permission checkboxes for Traces, Templates, and Scores You must select at least one permission. Submitting with no permissions selected shows the validation message Select a role or at least one permission. Custom permissions form scrolled to show all permission groups with a red validation error requiring at least one permission

​
Copy the key

After the key is created, the dashboard shows the key value once. Copy it now — it cannot be retrieved later. Post-create dialog showing the generated API key value with a copy icon and a warning that the key won't be saved
The key is shown once. If you lose it, you must delete the key and create a new one — AgentMark does not store the raw key value after this step.
Store the key in a secrets manager and load it from environment variables in your application: 
AGENTMARK_API_KEY=sk_agentmark_your_key_here
AGENTMARK_APP_ID=app_your_app_id_here
Both variables are documented in Environment Variables.

​
Edit key permissions

To change a key’s permissions, click the pencil icon next to the key in the list. API Keys list showing a single key row with Name, Created By, and Created At columns and pencil and trash action icons The edit modal works the same as the create modal — pick a role or toggle individual permissions. The Custom view shows every permission grouped by resource: Edit API Key Permissions modal with the Custom role selected, showing ungrouped permission checkboxes Selecting Full Access reveals the complete permission set the key will carry: Edit API Key Permissions modal with the Full Access role selected, showing every permission chip including trace, template, score, span, session, dataset, metrics, and experiment permissions Click Save to apply. The key value does not change, so your deployed integrations continue working with the new permissions immediately — no redeploy required. API Keys list after saving an edit, showing the same key with an updated timestamp
Edits apply to the same key value, so you can tighten or loosen permissions on a production key without rotating secrets.

​
Delete a key

Click the red trash icon next to a key and confirm the deletion. API Keys list back to the empty state after the key was deleted
Deletion is immediate. Any integration still using the deleted key will start receiving 401 Unauthorized on the next request.

​
Rotate a key

To rotate a key without downtime:
  1. Create a new key with the same permissions.
  2. Copy the new value and update AGENTMARK_API_KEY in your deployment (or secrets manager).
  3. Confirm your application is using the new key (check traces or logs for the expected activity).
  4. Delete the old key from the dashboard.
This ordering guarantees no 401 gap — the old key keeps working until you delete it.

​
Related reading

​
Have Questions?

We’re here to help! Choose the best way to reach us: