Skip to main content
API keys authenticate every request to the AgentMark Gateway. Each key covers a single app and environment, 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 and access control.

​
Locate the API keys settings

Open the AgentMark Dashboard, switch to the app and environment you want to scope the key to (both 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
Each key covers only the app and environment shown in the breadcrumb, and the list shows only the selected environment’s keys. A key created here can’t access any other app’s, or any other environment’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.write, 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.write, template.read, and score.write permission chips 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. 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. The form groups permissions by resource (Traces, Templates, Scores, Spans, Sessions, Datasets, Metrics, Experiments, Annotation Queues, API Keys, Deployments, Environments, Alerts, Apps) so you can mix and match. For example, use 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 you create the key, the Dashboard shows its value once. Copy it now; you can’t retrieve it later. Post-create dialog showing the generated API key value with a copy icon and a warning that AgentMark won't save the key
The Dashboard shows the key once. If you lose it, you must delete the key and create a new one. AgentMark doesn’t store the raw key value after this step.
Store the key in a secrets manager and load it from environment variables in your application:
Environment variables documents both 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 carries: 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 doesn’t 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 you deleted the key
Deletion is immediate. Any integration still using the deleted key starts 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?

Reach out any time: