self-IAM documentation

Rate limits & usage

How quota is enforced — and why failures still count.

Authentication & sessions

The hybrid JWT + cookie session model.

Identities & organizations

Separate collections and one-account-everywhere membership.

Security model

How credentials and keys are protected.

Pricing plans

Free · Pro · Enterprise — see the pricing page for full details.

Create a user and start a session. Routes to the `accounts` collection for the self-IAM organization and the shared `clients` collection for every other organization.

Auth

Publishable API key (`Authorization: Bearer org_live_…`)

Request

• `username` — 3–32 chars, `[a-zA-Z0-9_]` (required)
• `email` — valid email (required)
• `password` — at least 8 characters (required)
• `phoneNumber` — optional, `^\+?[0-9\s\-()]{7,20}$`

Success

`201` — `{ status, token, user, session, organization, remainingOps, resetDate }`

Limits

One identity per collection; duplicate usernames/emails are rejected globally.

curl -X POST https://selfiam.site/api/v1/auth/signup \
  -H "Authorization: Bearer org_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "username": "jane", "email": "jane@example.com", "password": "SuperSecret!23", "phoneNumber": "+14155550123" }'

Sign a user in by username or email with a password or QuickHash. Adds the calling organization to the identity's memberships (`organizationIds`) so one account works across organizations.

Auth

Publishable API key

Request

• `method` — `"username"` or `"email"` (required)
• `identity` — the username or email (required)
• `password` — plaintext password (required unless `quickHash` given)
• `quickHash` — optional replayable hash (`bcrypt(identity + ":" + password)`)

Success

`200` — `{ status, token, user, session, organization, remainingOps, resetDate }`

Limits

Token TTL 15 min; membership add is idempotent.

curl -X POST https://selfiam.site/api/v1/auth/verify \
  -H "Authorization: Bearer org_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "method": "username", "identity": "jane", "password": "SuperSecret!23" }'

Resolve the current user behind a session token (JWT). Used by the widget on load to revalidate sessions and by server helpers for page-level auth.

Auth

Session token (`Authorization: Bearer <jwt>` or `ck_session` cookie)

Success

`200` — `{ status, user, session: { expiresAt } }`

Limits

Public fields only (no hashes, no internal ids).

curl https://selfiam.site/api/v1/auth/me -H "Authorization: Bearer <jwt>"

Slide a still-valid session forward and return a fresh token + cookie.

Auth

Session token

Success

`200` — fresh `{ status, token, user, session }`

Limits

Only renews before the 15-min TTL; revoked sessions cannot be refreshed.

curl -X POST https://selfiam.site/api/v1/auth/refresh -H "Authorization: Bearer <jwt>"

Revoke the current session centrally (deletes the session record, so the JWT can never be refreshed). With `?all=1` it revokes every session for the user.

Auth

Session token

Request

• Query: `?all=1` (optional) — log out of all devices

Success

`200` — `{ status: "success" }`

Limits

Idempotent; already-revoked tokens return 401.

curl -X POST https://selfiam.site/api/v1/auth/logout?all=1 -H "Authorization: Bearer <jwt>"

Return a Google OAuth consent URL for the calling organization. On success the callback redirects back with `?contactkit_token=` or `?contactkit_error=`.

Auth

Publishable API key

Request

• `redirectUrl` — where the browser should return after consent (required)

Success

`200` — `{ status, authUrl }`

Limits

A Google account is linked once and never re-bound by another org's API.

curl -X POST https://selfiam.site/api/v1/auth/google/authorize \
  -H "Authorization: Bearer org_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "redirectUrl": "https://my-app.com/auth/callback" }'

List the session organization's API keys with usage stats (GET) or issue a new key (POST). Key hashes never leave the server.

Auth

Accounts session token (dashboard login)

Request

• POST body: `name` — key name/note, 1–64 chars (required; rejected otherwise)

Success

GET `200` — key list with `preview`, `dailyUsage`, `remainingOps`, `resetDate`. POST `201` — `{ apiKey, name, organizationId }` (raw key shown once).

Limits

Daily quota per key (100 Free / 98,765 Pro / unlimited Enterprise).

curl -X POST https://selfiam.site/api/v1/keys \
  -H "Authorization: Bearer <jwt>" -H "Content-Type: application/json" \
  -d '{ "name": "Production web app" }'

List legacy IAM users belonging to the session organization — public profile fields only.

Auth

Accounts session token

Success

`200` — `{ status, users: [{ id, username, email, phoneNumber, createdAt }] }`

Limits

Projection excludes passwordHash/quickHash/googleId.

curl https://selfiam.site/api/v1/users -H "Authorization: Bearer <jwt>"

List client users (end-users created on client websites) that are members of the session organization. Uses the shared `clients` collection.

Auth

Accounts session token

Success

`200` — `{ status, count, clients: [{ id, username, email, phoneNumber, createdAt }] }`

Limits

Public fields only; org-scoped via `organizationIds`.

curl https://selfiam.site/api/v1/clients -H "Authorization: Bearer <jwt>"

Verify a client user's username + password/QuickHash. Mirrors the legacy IAM route against the shared `clients` collection, scoped to the calling organization.

Auth

Publishable API key + `X-Username` + `X-Password` or `X-Quick-Hash`

Success

`200` — `{ status, authenticated, username, usernameHash, remainingOps, resetDate }`

Limits

Client must be a member of the calling org; dummy bcrypt runs for timing safety.

curl https://selfiam.site/api/v1/clients/unamehash \
  -H "Authorization: Bearer org_live_..." \
  -H "X-Username: jane" -H "X-Password: SuperSecret!23"

Email variant of the client verification endpoint — validates `X-Email` + password/QuickHash.

Auth

Publishable API key + `X-Email` + `X-Password` or `X-Quick-Hash`

Success

`200` — `{ status, authenticated, email, emailHash, remainingOps, resetDate }`

Limits

Client must belong to the calling org.

curl https://selfiam.site/api/v1/clients/emailhash \
  -H "Authorization: Bearer org_live_..." \
  -H "X-Email: jane@example.com" -H "X-Password: SuperSecret!23"

Request or verify a 6-digit WhatsApp OTP for a client user (requires a linked `phoneNumber`). Codes are stored SHA-256-hashed with a 5-minute TTL and are single-use.

Auth

Publishable API key

Request

• `action: "request"` + header `X-Username` → sends the code
• `action: "verify"` + headers `X-Username` + `X-Otp` → validates it

Success

request `200` — `{ status, message, deliveredVia, remainingOps }`. verify `200` — `{ status, authenticated, username, usernameHash }`.

Limits

Requires WHATSAPP_API_KEY + WHATSAPP_PHONE_NUMBER_ID; otherwise delivery is skipped (devCode returned in non-production).

curl -X POST https://selfiam.site/api/v1/clients/whatsapp-otp \
  -H "Authorization: Bearer org_live_..." -H "X-Username: jane" \
  -H "Content-Type: application/json" -d '{ "action": "request" }'

Original username + password/QuickHash verification against the legacy `users` collection.

Auth

Publishable API key + `X-Username` + `X-Password` or `X-Quick-Hash`

Success

`200` — `{ status, authenticated, username, usernameHash }`

Limits

Same 100/day quota; gate runs before validation so failures count.

curl https://selfiam.site/api/v1/unamehash \
  -H "Authorization: Bearer org_live_..." \
  -H "X-Username: john_doe" -H "X-Password: CorrectHorseBatteryStaple1!"

Email-based password/QuickHash verification against legacy `users`.

Auth

Publishable API key + `X-Email` + `X-Password` or `X-Quick-Hash`

Success

`200` — `{ status, authenticated, email, emailHash }`

Limits

Same quota behavior as above.

curl https://selfiam.site/api/v1/emailhash \
  -H "Authorization: Bearer org_live_..." \
  -H "X-Email: john@selfiam.example" -H "X-Password: CorrectHorseBatteryStaple1!"

Original WhatsApp OTP request/verify against legacy `users`.

Auth

Publishable API key

Request

• `action: "request"` / `"verify"` + `X-Username` (+ `X-Otp`)

Success

`200` — request: OTP sent; verify: `{ status, authenticated, username }`

Limits

Same WhatsApp env requirements as the clients variant.

curl -X POST https://selfiam.site/api/v1/whatsapp-otp \
  -H "Authorization: Bearer org_live_..." -H "X-Username: john_doe" \
  -H "Content-Type: application/json" -d '{ "action": "request" }'

Accept a contact-form submission and persist it to the `messages` collection. This is the endpoint the `ContactForm` widget posts to.

Auth

Publishable API key

Request

• `name` (≤200), `email` (valid, ≤320), `subject` (≤200, optional), `message` (≤5000)

Success

`201` — `{ status, messageId, createdAt, remainingOps, resetDate }`

Limits

Field length caps; gate runs before body validation so bad requests still count.

curl -X POST https://selfiam.site/api/v1/contact/messages \
  -H "Authorization: Bearer org_live_..." -H "Content-Type: application/json" \
  -d '{ "name": "Jane Doe", "email": "jane@example.com", "subject": "Pricing", "message": "Do you offer a free tier?" }'

Public organization profile (name, slug, allowedRoutes) used for top-bar branding.

Auth

None

Request

• Query: `organizationSlug` (optional, defaults to `self-iam`)

Success

`200` — `{ status, organization: { id, name, slug, allowedRoutes } }`

Limits

Public read-only.

curl "https://selfiam.site/api/v1/org?organizationSlug=self-iam"