Register a non-human identity via curl
Goal: register one non-human identity (NHI) with a single curl call and verify the audit row. This is the smallest possible end-to-end loop with AtmanID’s API platform — no SDK, no framework, just an HTTP request and a database row to inspect.
If you’re new to AtmanID generally, read What is AtmanID? first for context on why NHIs need their own identity primitive distinct from human users.
Prerequisites
You need two things before starting:
- An AtmanID tenant — sign in to the dashboard at least once (at your tenant’s base URL, provided with your onboarding)
- An API key with the
write:nhiscope (addread:audit_logsto verify the audit row from the API in step 3) — mint atSettings → API Keys → Create new key. Copy the secret once, store it somewhere safe (you can’t retrieve it later). The key’s owner must also hold the permission to manage non-human identities; it is checked on every call.
Set the key in your shell before running the curl below:
export ATMANID_API_KEY="atman_YOUR_KEY_HERE"export ATMANID_BASE_URL="https://your-atmanid-instance.com" # replace with your AtmanID base URL1. Make the call
The body matches AgentCreateBody in the API spec. idempotency_key + name + type + owner_team + owner_email are required; everything else is optional (environment is one of Production (default), Staging, Development, Testing). The idempotency_key dedupes retries within a 24-hour window — set it to something deterministic like <purpose>-<date> so re-running the curl doesn’t create a duplicate.
curl -X POST \ -H "Authorization: Bearer $ATMANID_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "idempotency_key": "register-stripe-listener-2026-04-29", "name": "stripe-webhook-listener", "type": "External AI Tool", "framework": "node-stripe-sdk", "owner_team": "payments", "owner_email": "payments-eng@example.com", "environment": "Production", "vendor": "stripe", "purpose": "Listens for Stripe webhook events and triggers reconciliation" }' \ "$ATMANID_BASE_URL/api/v1/agents"2. Read the response
On success the API returns 201 with the new agent_id and a request_id (in the X-Request-Id response header) that you can use to grep the audit log:
{ "ok": true, "agent_id": "agt-v1-7a2c8d9f1234", "status": "PENDING_REVIEW", "name": "stripe-webhook-listener", "advisory": true, "message": "Agent registered. Status is PENDING_REVIEW — an administrator must approve before full policy enforcement activates.", "next_step": "An AtmanID administrator will review and approve. Until then, advisory-mode policy applies."}Two things to capture for the next step:
Re-running the same call with the same idempotency_key within 24 hours returns 200 with "cached": true and the original agent_id instead of creating a duplicate.
agent_id— the canonical ID for this NHI; use it in subsequent API callsX-Request-Idresponse header — typicallyreq_01KQ...— same value lands in the corresponding audit record
One ID, two tables, full forensic trail. This is the audit chain pattern you’ll see across every AtmanID API call.
3. Verify in the audit trail
In the dashboard, navigate to Audit & Reports and search by your X-Request-Id. You’ll see exactly one row with:
action_type = AGENT_REGISTEREDtarget_resource_idmatching youragent_idtarget_resource_type = ai_agentactor_nameshowing the API key name (e.g. “stripe-integration-key”)
If you prefer to verify via the API directly (needs read:audit_logs), list recent AGENT_REGISTERED events and match on request_id — the audit API filters by action type and time, not by request id:
curl -s -H "Authorization: Bearer $ATMANID_API_KEY" \ "$ATMANID_BASE_URL/api/v1/audit?action_type=AGENT_REGISTERED&since=2026-10-10T00:00:00Z&limit=100" \ | jq '.data[] | select(.request_id == "req_01KQ...")'What just happened
Three things:
- One
POST /api/v1/agentsregistered one agent withstatus = PENDING_REVIEW - A linked audit record was written with the same
request_id, sametarget_resource_id - An identity admin can now approve the agent in
Machine Identity (NHI)to activate full policy enforcement (move fromPENDING_REVIEWtoACTIVE)
The PENDING_REVIEW state is intentional. NHIs land in a holding pen by default so an identity admin reviews them before they can perform privileged operations. This is how AtmanID enforces “least privilege from the moment of identity creation” — distinct from the JML “Joiner” flow for humans, which auto-provisions baseline access on creation.
Common errors
| Status | error.code |
What’s wrong | Fix |
|---|---|---|---|
| 401 | UNAUTHENTICATED |
No Authorization: Bearer header, or the key is malformed, revoked, expired or typo’d |
Send Authorization: Bearer $ATMANID_API_KEY; mint a fresh key if needed |
| 403 | RBAC_DENIED |
Key lacks write:nhi, or the key owner’s role can’t manage non-human identities |
Mint a key with write:nhi selected, owned by someone with that permission |
| 400 | VALIDATION_ERROR |
Required field missing or wrong type | Check error.details for the specific field |
| 400 | OWNER_GROUP_NOT_FOUND |
owner_group_name doesn’t match a group in your tenant |
Use an existing group name, or omit the field |
| 409 | AGENT_ALREADY_EXISTS / AGENT_NAME_CONFLICT |
An agent with this name already exists in your tenant (ACTIVE, or another status) |
Pick a unique name, or clear the prior registration first. A new idempotency_key will not get past this check |
| 409 | TENANT_QUOTA_EXCEEDED / TIER_QUOTA_EXCEEDED / TENANT_QUOTA_UNCONFIGURED |
Your tenant’s agent quota is reached or not configured | Deactivate unused agents or ask your administrator to raise the quota |
| 429 | RATE_LIMITED |
Hit the per-key rate limit | Wait for Retry-After, then retry with the same idempotency_key (see Common Patterns) |
All errors return the standard envelope: { error: { code, message, request_id, details? } }. Quote the request_id in support requests; it matches the X-Request-Id response header.
Going further
- For multi-agent GitOps workflows, see the GitHub Action recipe (coming soon)
- To tag agents you own and avoid mover/leaver flows touching anyone else’s, set
managed_byon the body — see GitOps NHI lifecycle - For TypeScript instead of curl, see First SDK script — same scenario, typed responses, retry logic, IDE autocomplete
- For the full endpoint surface, see API Reference → Agents
© AtmanID · Privacy