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_ownerorsuper_adminrole (needed to issue API keys) curlinstalled (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:
- Log in to your AtmanID tenant (at your tenant’s base URL, provided with your onboarding)
- Navigate to Platform Config → Integrations & API → API Keys (
/dashboard/settings/api-keys) - Click Create Key
- Enter a Key Name (e.g., “First API call tutorial”)
- Under Scopes, select just
read:users - Fill in Purpose (required, at least 20 characters) and pick how long the key is Valid for
- Click Create Key
- 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:
export ATMANID_API_KEY="atman_your_key_here"export ATMANID_BASE_URL="https://<your-atmanid-instance>" # your tenant's base URLStep 2 — Make your first call
The simplest read: list users in your tenant. The endpoint is GET /api/v1/users.
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-Idheader — keep it when you need support
Step 3 — Parse the response
In whatever language you’re working in:
bash + jq:
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, requestsr = 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:
- Open the AtmanID web app → Platform Config → Integrations & API → API Keys
- On your key’s row, click the View usage stats icon
- You should see the request counted, with
GET /api/v1/usersamong 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
- First SDK script — same flow with the TypeScript SDK, gets you typed responses + error classes
- Common patterns — pagination across multiple pages, error handling, retries, webhook verification
- API Reference — the full v1 surface
- Concepts → Architecture overview — the security model behind why your API key only sees your tenant
© AtmanID · Privacy