Skip to content

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:nhi scope (add read:audit_logs to verify the audit row from the API in step 3) — mint at Settings → 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:

Terminal window
export ATMANID_API_KEY="atman_YOUR_KEY_HERE"
export ATMANID_BASE_URL="https://your-atmanid-instance.com" # replace with your AtmanID base URL

1. 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.

Terminal window
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 calls
  • X-Request-Id response header — typically req_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_REGISTERED
  • target_resource_id matching your agent_id
  • target_resource_type = ai_agent
  • actor_name showing 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:

Terminal window
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/agents registered one agent with status = PENDING_REVIEW
  • A linked audit record was written with the same request_id, same target_resource_id
  • An identity admin can now approve the agent in Machine Identity (NHI) to activate full policy enforcement (move from PENDING_REVIEW to ACTIVE)

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

© AtmanID · Privacy