Skip to content

First API call

This tutorial walks through making your first authenticated request to the AtmanID v1 REST API. We’ll use curl for transport-level clarity; the First SDK script tutorial covers the same flow with the TypeScript SDK once you’re past the basics.

Time estimate: ~10 minutes including the API key request.

Prerequisites

  • An AtmanID account with the identity_admin, tenant_owner or super_admin role (needed to issue API keys)
  • curl installed (or any HTTP client — Postman, Insomnia, Bruno, your language’s standard library)
  • A terminal

Step 1 — Get an API key

API keys are issued from the AtmanID web app:

  1. Log in to your AtmanID tenant (at your tenant’s base URL, provided with your onboarding)
  2. Navigate to Platform Config → Integrations & API → API Keys (/dashboard/settings/api-keys)
  3. Click Create Key
  4. Enter a Key Name (e.g., “First API call tutorial”)
  5. Under Scopes, select just read:users
  6. Fill in Purpose (required, at least 20 characters) and pick how long the key is Valid for
  7. Click Create Key
  8. Copy the key immediately — it starts with atman_ and is shown only once

Treat the key like a password. Don’t commit it to source control. For this tutorial, set it as an environment variable — along with the base URL every snippet below uses:

Terminal window
export ATMANID_API_KEY="atman_your_key_here"
export ATMANID_BASE_URL="https://<your-atmanid-instance>" # your tenant's base URL

Step 2 — Make your first call

The simplest read: list users in your tenant. The endpoint is GET /api/v1/users.

Terminal window
curl -X GET "$ATMANID_BASE_URL/api/v1/users" \
-H "Authorization: Bearer $ATMANID_API_KEY" \
-H "Accept: application/json"

Expected response shape (truncated for clarity):

{
"data": [
{
"id": "3f2a9c1e-7b4d-4e8a-9c21-5d6e7f8a9b0c",
"email": "sarah.chen@example.com",
"first_name": "Sarah",
"last_name": "Chen",
"full_name": "Sarah Chen",
"department": "Security",
"title": "Identity Administrator",
"status": "ACTIVE",
"identity_type": "employee",
"role": "Identity Administrator",
"entitlement_count": 12,
"last_login_at": "2026-05-09T17:42:08.000Z",
"created_at": "2026-01-15T08:23:11.000Z"
},
/* ... up to 25 users by default ... */
],
"total": 48,
"page": 1,
"limit": 25,
"total_pages": 2
}

What just happened:

  • Authorization: Bearer atman_... authenticated the request as that API key (its scopes decide what it may call)
  • The endpoint returned users in YOUR tenant only — the tenant comes from the key itself and isolation is enforced at the database layer, no parameter required
  • Response follows the standard pagination shape ({ data, total, page, limit, total_pages }). Use ?page= and ?limit= (default 25, max 100) to move through it
  • Every response carries an X-Request-Id header — keep it when you need support

Step 3 — Parse the response

In whatever language you’re working in:

bash + jq:

Terminal window
curl -s -X GET "$ATMANID_BASE_URL/api/v1/users" \
-H "Authorization: Bearer $ATMANID_API_KEY" \
| jq '.data[] | {email, status, last_login_at}'

Python:

import os, requests
r = requests.get(
f"{os.environ['ATMANID_BASE_URL']}/api/v1/users",
headers={"Authorization": f"Bearer {os.environ['ATMANID_API_KEY']}"},
)
for user in r.json()["data"]:
print(f"{user['email']:40} {user['status']:15} {user['last_login_at']}")

TypeScript (without SDK):

const r = await fetch(`${process.env.ATMANID_BASE_URL}/api/v1/users`, {
headers: { Authorization: `Bearer ${process.env.ATMANID_API_KEY}` },
});
const { data } = await r.json();
for (const user of data) {
console.log(`${user.email} ${user.status} ${user.last_login_at}`);
}

For TypeScript specifically, the SDK provides typed responses, a retry on server and network errors, and error classes out of the box — see the First SDK script tutorial next.

Step 4 — Verify the call was recorded

Every API call is metered against the key that made it. Verify yours landed:

  1. Open the AtmanID web app → Platform Config → Integrations & API → API Keys
  2. On your key’s row, click the View usage stats icon
  3. You should see the request counted, with GET /api/v1/users among the key’s top endpoints. The key’s Last used column updates too

Read-only calls like this one are metered rather than written to the audit log. Actions that change state — creating the key you just used, approving access, registering an agent — are written to the hash-chained audit log; see the architecture overview.

Common first-call errors

Errors come back in one shape: { "error": { "code": "...", "message": "...", "request_id": "..." } }. Branch on error.code, not the message.

Symptom Cause Fix
401 with code UNAUTHENTICATED Missing or invalid Authorization header, or a revoked/expired key Verify key starts with atman_ and the env var resolved (echo $ATMANID_API_KEY)
403 with code RBAC_DENIED (“Insufficient scopes”) Key doesn’t have the required scope Key scopes can’t be edited — create a new key with read:users in Platform Config → Integrations & API → API Keys
429 with code RATE_LIMITED Rate limit hit (60 req/min for a standard-tier key) Back off per Retry-After header — see Common patterns
5xx Service issue Check $ATMANID_BASE_URL/api/healthz for service status; if 200, email hello@atmanid.com with the X-Request-Id from the response headers

What you’ve validated

By completing this tutorial:

  • ✅ You can authenticate to AtmanID via API key
  • ✅ You understand the standard paginated response shape
  • ✅ Your tenant data is reachable + correctly scoped
  • ✅ Your key’s usage is being recorded

Where to go next

© AtmanID · Privacy