Management API

Create, find, update, import, block and delete users, create login links and end sessions over HTTPS.

Manage the users and sessions of one tenant environment over HTTPS. The machine-readable version is /openapi.json (OpenAPI 3.1).

#Base URL and authentication

https://<tenant>.9in.io/api/v1           production
https://<tenant>-sandbox.9in.io/api/v1   sandbox (separate users)
https://login.acme.com/api/v1            a custom domain

Every request needs Authorization: Bearer <token>, a client-credentials token of a confidential application that was given management scopes (Applications → app → API Access → Management API):

TOKEN=$(curl -s -X POST https://acme.9in.io/oauth/token -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials -d scope="management:users:read management:users:write" | jq -r .access_token)

The application is re-checked on every call: removing a scope or deleting the application takes effect at once. With @9in-io/sdk/server, ManagementClient gets and caches tokens itself, asking each call for only the scope it needs.

#Endpoints

#The user object

What the API returns (OpenID Connect claim names):

{
  "id": "usr_8k2m4q",
  "email": "jane@acme.com",
  "email_verified": true,
  "phone_number": null,
  "phone_number_verified": false,
  "username": null,
  "preferred_username": null,
  "name": "Jane Doe",
  "given_name": "Jane",
  "middle_name": null,
  "family_name": "Doe",
  "nickname": null,
  "gender": null,
  "website": null,
  "picture": null,
  "locale": "en",
  "zoneinfo": null,
  "birthdate": null,
  "blocked": false,
  "metadata": { "plan": "pro", "fields": { "company": "Acme" } },
  "createdAt": 1794200000000,
  "updatedAt": 1794200000000,
  "lastLoginAt": 1794203000000,
  "loginCount": 12
}

Times are milliseconds since the epoch. Custom profile fields live in metadata.fields.

#Creating and updating

POST /users and PATCH /users/{id} take these fields. Three names differ from the output: emailVerified, phone and phoneVerified.

curl -X POST https://acme.9in.io/api/v1/users -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "email": "jane@acme.com", "emailVerified": true, "name": "Jane Doe", "password": "…" }'
# → 201 { "user": { … } }

Errors: 400 invalid_user (with details: [{ path, message }]), invalid_email, invalid_phone, identifier_required, unsupported_password_hash; 409 identifier_taken; 404 not_found.

#Listing and searching

GET /users returns newest first: { "users": [...], "nextCursor": "…" | null, "total": 1234 }. Pass nextCursor back as cursor for the next page. q matches email, username, phone and name (substring) or an exact id; limit is 1 to 200 (default 50).

#Getting one user

GET /users/{id}:

{
  "user": { … },
  "identities": [{ "connection": "social:google", "subject": "1098…", "userId": "usr_…", "profile": {}, "createdAt": 1794200000000 }],
  "sessions": [{ "sid": "…", "userId": "usr_…", "authTime": 1794199000, "amr": ["pwd"], "ip": "81.2.69.160", "userAgent": "…", "createdAt": …, "lastSeenAt": …, "expiresAt": …, "revokedAt": null }],
  "hasPassword": true,
  "mfa": { "enabled": true, "since": 1794100000000, "recoveryCodesLeft": 9 }
}

#Importing

POST /users/import with { "users": [...], "on_conflict": "skip" | "update", "source": "legacy" }. Up to 500 users (50 with plain-text passwords). Records may also carry id (kept as the user id), identities ([{ connection, subject }]), createdAt and lastLoginAt. Returns { "results": [{ index, ok, status: "created" | "updated" | "skipped" | "failed", id?, reason?, error?, details? }] }, one per record, in order. See Importing users.

#Login links

POST /users/{id}/login-link with optional { "return_to": "https://app.acme.com/callback", "ttl_seconds": 600 } returns 201 { "url": "…", "expires_at": 1794200600 }. See Login links.

#Errors

{ "error": "insufficient_scope", "error_description": "requires management:users:write" }