Authentication
without the pain.

Request body

{
  "email": "alice@acme.com",
  "username": "alice",   // optional under the AutoFromEmail policy — see below
  "password": "S3cure!Pass"
}

Response — 201 Created

{ "id": "01H..." }

Errors

• user.email_taken — 409
• user.username.taken — 409 (only under the Reject policy)
• user.username.empty — 400 (username omitted under a non-Auto policy)
• user.password_weak — 400
• user.password_pwned — 400 (breach-check validation)

Username policy (Environment Settings → Sign-in)

The environment's UsernameCollisionPolicy controls what happens when the requested username is missing or already taken:

• reject — Default. Username required. Return 409 on conflict.
• suffix — Username required. Conflict → append smallest free integer (alice → alice2).
• random — Username required. Conflict → append short base36 tag (alice.k4a1).
• autoFromEmail — Username optional. When omitted, Authyon derives one from the email local-part (alice+dev@x.com → alice.dev) and applies the suffix ladder on conflict.

Request body

{
  "email": "alice@acme.com",        // or "username"
  "password": "S3cure!Pass",
  "tenantSlug": "acme"              // optional — picks the active tenant on the token
}

Response — 200 (no 2FA)

{
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "rt_...",
  "expiresIn": 1800,
  "user": { "id": "01H...", "email": "..." }
}

Response — 200 (2FA required)

{
  "twoFactorRequired": true,
  "challengeId": "chg_...",
  "methods": ["authenticator", "email"],
  "emailHint": "a****@a***.com"
}

Then call /auth/2fa/challenge with the code.

Rate limits

• 10 req / 5min / IP
• 5 req / 5min / email — protects against credential stuffing

Request body

{ "refreshToken": "rt_..." }

Response — 200

{
  "accessToken": "eyJ...",
  "refreshToken": "rt_...",
  "expiresIn": 1800
}

Request body (optional)

{ "refreshToken": "rt_..." }

Response — 204 No Content

Response — 200

{
  "id": "01H...",
  "email": "alice@acme.com",
  "tenants": [{ "id": "...", "slug": "acme", "roles": ["admin"] }],
  "activeTenant": "acme",
  "permissions": ["orders:read", "orders:write"]
}

Create a new tenant (self-service)

Any signed-in user can create a tenant when the environment allows it. The moment the tenant is created, the caller becomes its first member and automatically gets the three permissions needed to manage it (tenants:manage, tenants:members:invite, tenants:members:remove). So there's no "chicken and egg" problem — you can rename or invite people right after creating.

curl -X POST https://api.authyon.com/auth/tenants \
  -H "X-Authyon-Env: pk_live_..." \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Inc","slug":"acme"}'

Enable it per environment: Environment Settings → Sign-in → Self-service tenant creation. When off, this endpoint returns environment.self_service_disabled (403). Rate-limited to 5 creations per user / hour and 20 per IP / hour.

Unblocking a user who hit the cap. A user tripped by the 5/hour ceiling gets rate_limit.exceeded until the Redis bucket ages out (max 60 min). Waiting for the TTL is fine for most cases — but if you need to release someone right now, open Users → <user> → Account and press Clear rate limits. It calls POST /platform/workspaces/{ws}/environments/{env}/users/{id}/reset-rate-limits, deletes every user-scoped bucket keyed on the caller's sub, and audits a UserRateLimitsCleared event. Lockout, disable and suspend flags are untouched — this only clears the throttle.

Read your tenant + members

Any member can hit these — no permission needed.

Manage the tenant (permission-gated)

These need the caller to hold a specific permission on the tenant. The person who created the tenant already has them; anyone else needs a role that grants the matching permission.

Errors to expect

• environment.self_service_disabled — 403. Env admin hasn't enabled self-service creation.
• tenant.not_found — 404.
• tenant.not_member — 401. The caller isn't a member (same shape whether the tenant exists or not, so no one can enumerate).
• tenant.permission_denied — 403. Member, but missing the permission for the mutation.
• tenant.member.email_not_found — 404 on invite. Send them a /auth/register link first.
• tenant.member.already_exists — 409 on invite.
• tenant.member.cannot_remove_self — 400 on self-remove.

Wiring the permissions: the mutation endpoints check custom permissions inside the tenant scope — they're not built-in. Create them in the platform UI (Environment → Permissions) and assign to a tenant role (e.g. tenant.admin) that the tenant owner holds. Members without the role can still read every non-mutation endpoint.

Error codes

• environment.header.missing — 401 (X-Authyon-Environment absent)
• tenant.not_found — 404
• tenant.not_member — 401 (caller isn't a member — same shape whether the tenant exists or not, to avoid enumeration)
• tenant.permission_denied — 403 (member but lacks the mutation permission)
• tenant.member.email_not_found — 404 (invite target isn't a user in this env yet — send them to /auth/register first)
• tenant.member.already_exists — 409
• tenant.member.cannot_remove_self — 400

Request body

{ "tenantSlug": "other-org" }

Revoke one

DELETE /auth/sessions/{sessionId}

Request body

{ "email": "alice@acme.com" }

Request body

{
  "token": "prt_...",
  "newPassword": "NewS3cure!"
}

Response — 200

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qrSvg": "<svg xmlns=...",
  "otpauthUri": "otpauth://totp/Authyon:..."
}

Request body

{ "code": "123456" }

Response — 200

{
  "recoveryCodes": ["a1b2-c3d4-...", ...]  // 10 codes, single-use
}

Request body

{
  "challengeId": "chg_...",
  "code": "123456",      // or "recoveryCode": "..."
  "method": "authenticator"  // or "email"
}

Response — 200: same tokens envelope as /auth/login.

Request (form-encoded)

grant_type=client_credentials
client_id=env_...
client_secret=...

Response — 200

{
  "access_token": "eyJ...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "env:admin"
}

Login-time error codes: user.disabled, user.suspended, user.deleted. Distinct codes so a client SDK can render the right UX (retry vs. contact-support).

Envelope shape

{
  "id":             "evt_0f7c…",
  "type":           "user.registered",
  "created":        1721512345,
  "workspace_id":   "…",
  "environment_id": "…",
  "data": {
    "user_id": "…",
    "email":   "alice@acme.com",
    "username": "alice"
  }
}

Signature verification (Node)

// header: X-Authyon-Signature: t=1721512345,v1=abc123…
const [ts, v1] = header.split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret)
  .update(`${ts}.${rawBody}`)
  .digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)))
  return res.status(401).end();
if (Math.abs(Date.now()/1000 - Number(ts)) > 300)   // reject >5min
  return res.status(401).end();

Headers on every POST Retries

2xx = success. 4xx (except 408 / 429) = permanent failure, no retry. Everything else retries with 5s / 30s / 5min / 30min / 2h backoff up to 6 total attempts, then marks the delivery failed and ticks the endpoint's consecutive-failure counter.

Managing endpoints

Enable auto-blocking (env setting)

PUT /env/settings
{
  "autoBlockDurationMinutes": 60   // 1..10080 (7d); null disables
}

Row shape: { id, ip, reason, userId?, blockedAt, expiresAt, isActive }. reason is user_disabled or user_suspended. userId is populated when the block was triggered by a known user probe.

Response — 200

{ "active": true, "sub": "...", "exp": 1735689600, "scope": "..." }

Response — 200

{
  "user": { "id": "...", "roles": [...], "permissions": [...] },
  "tenant": { "id": "...", "slug": "..." }
}