Copy
Every request to the Nomotic API requires authentication. This article explains how to create API keys, how to use them in requests, and what the different key scopes allow.
Creating an API key
Go to Settings → API Keys and click Create API Key. Give the key a name that describes what it will be used for — something like “production-agent” or “ci-pipeline” is clearer than “key1.”
Choose a scope:
Agentic — for SDK integrations and governed agents. Allows governance evaluations, audit trail reads, and agent status updates. This is the right scope for most agent integrations.
Write — for platform integrations that need to create or update resources. Allows everything Agentic allows, plus managing agents, policies, and context.
Read — for analytics, monitoring, and reporting tools. Read-only access to evaluations, audit trail, and agent status.
Admin — full access. Reserve this for internal tooling and automation, not for agents.
When you create a key, the full key value is shown exactly once. Copy it immediately and store it securely. Nomotic does not store the full key — only a hashed version for verification. If you lose it, generate a new one.
Using your API key
Include your API key in the Authorization header of every request:
Authorization: Bearer nm_live_your_key_hereAll API requests go to:
https://amp.nomotic.ai/api/v1/Example request to list your agents:
GET https://amp.nomotic.ai/api/v1/agents
Authorization: Bearer nm_live_your_key_here
Content-Type: application/jsonKey prefixes
Every Nomotic API key starts with nm_live_ for production keys. If you are building a development integration, you can use a separate key and label it accordingly in the dashboard. There is no separate test mode — governance evaluations in development count toward your monthly evaluation limit just like production evaluations.
Rotating keys
To rotate a key, create a new one with the same scope, update your integration to use the new key, verify it is working, then revoke the old key. Revoking is immediate — any request using the revoked key will receive a 401 Unauthorized response.
Rate limits
API rate limits are based on your plan:
Free: 60 requests per minute Team: 500 requests per minute Business: 2,000 requests per minute Enterprise: Custom
If you exceed your rate limit, requests return a 429 Too Many Requests response with a Retry-After header indicating when to try again.
Common authentication errors
401 Unauthorized — your API key is missing, malformed, or has been revoked. Check that the Authorization header is present and correctly formatted.
403 Forbidden — your API key does not have the scope required for this endpoint. For example, a Read key cannot submit governance evaluations.
429 Too Many Requests — you have hit your rate limit. Implement exponential backoff in your integration.
Security best practices
Never put API keys in source code or commit them to version control. Use environment variables or a secrets manager. Rotate keys periodically, especially after team member offboarding. Use the minimum scope required for each integration — an agent that only needs to submit evaluations should use an Agentic key, not an Admin key.