Documentation

UnityAuth API

UnityAuth is the identity provider for every UNX app. It handles accounts, email verification, sign-in, password reset, sessions, roles, tenants and the audit log. This page documents everything live on https://auth.unx.ng today.

Core concepts

Sessions are cookies

A successful sign-in sets an HttpOnly, Secure session cookie. Browsers send it automatically with credentials: "include". Never copy session tokens into localStorage.

Trusted origins

Requests that change state must carry an Origin header from an allowed site (UNX apps on *.unx.ng). Ask the UNX team to add your app's origin.

Verified email

Email and password accounts must verify their email with a 6-digit code before the password works. Passwordless and social sign-ins arrive verified.

Stable ids

Ids are prefixed and time-sortable: usr_ users, ses_ sessions, org_ tenants, aud_ audit events. Link your data to them.

API reference

Badges show what each call needs: Public no session, Signed in a session cookie, permission a role that grants that permission.

Sign up and email verification

Email and password sign-up creates the account and emails a 6-digit code. The account cannot sign in with its password until the email is verified; verifying signs the user in.

{
  "name": "Ada Obi",
  "email": "ada@example.com",
  "password": "at-least-8-chars",
  "username": "adaobi"          // optional; generated when omitted
}

{ "token": null, "user": { "id": "usr_…", "email": "ada@example.com", "emailVerified": false, "username": "adaobi" } }

{ "email": "ada@example.com", "otp": "123456" }

{ "status": true, "token": "…", "user": { "emailVerified": true, … } }

{ "email": "ada@example.com", "type": "email-verification" }   // or "sign-in"

{ "success": true }

Sign in

Every method resolves to the same UNX user. A successful sign-in sets an HttpOnly session cookie; there is no token for the browser to store.

{ "email": "ada@example.com", "password": "…", "rememberMe": true }

{ "redirect": false, "token": "…", "user": { … } }

{ "username": "adaobi", "password": "…", "rememberMe": true }

{ "email": "ada@example.com", "otp": "123456" }

{ "provider": "google", "callbackURL": "https://your.app/after-login", "errorCallbackURL": "https://your.app/login" }

{ "url": "https://accounts.google.com/…", "redirect": true }

{ "providers": ["google"] }

{ "user": { … }, "session": { "id": "ses_…", "expiresAt": "…", "location": "Abuja, Nigeria" } }

{}

Password reset

One email carries two ways to reset: a link (valid 60 minutes) and a 6-digit code (valid 5 minutes). Using either cancels the other, and a reset signs the account out on every device. Unknown emails get the same response and no email.

{ "email": "ada@example.com" }

{ "success": true }

{ "email": "ada@example.com", "otp": "123456", "password": "new-password" }

{ "success": true }

{ "token": "…", "newPassword": "new-password" }

{ "status": true }

Account, sessions and devices

Endpoints for the signed-in user. Each session records its device, IP address and an approximate location.

{ "role": "user", "roles": ["user"], "permissions": [] }

{ "items": [{ "role": "member", "tenant": { "tid": "unityx", "name": "UnityHUB", … } }] }

{ "name": "Ada O." }

{ "currentPassword": "…", "newPassword": "…", "revokeOtherSessions": true }

{ "token": "<session token from list-sessions>" }

{}

{ "provider": "google", "callbackURL": "https://your.app/account", "errorCallbackURL": "https://your.app/account" }

{ "url": "https://accounts.google.com/…", "redirect": true }

{ "accountId": "acc_… (id from list-accounts)" }

Tenants and API keys

Create and manage organisations (tenants) and their API keys, as in the developer console. Owners and admins of a tenant can edit it and manage keys; only the owner can delete it. The default tenant (UnityHUB, unityx) cannot be deleted. Writes must come from a trusted Origin.

{
  "name": "Acme Ventures",
  "tid": "acme-ventures",        // optional, permanent; derived from name if omitted
  "description": "…",
  "url": "https://acme.example"
}

{ "id": "org_…", "tid": "acme-ventures", "name": "Acme Ventures", "status": "active", … }   // 201

{ "id": "org_…", "tid": "…", "myRole": "owner", "isDefault": false, "counts": { "members": 1, "apiKeys": 0 } }

{ "name": "Acme Ventures Ltd", "url": "https://acme.example" }

{ "name": "Production server", "expiresInDays": 365 }   // expiresInDays optional

{ "key": "unx_live_…", "apiKey": { "id": "key_…", "prefix": "unx_live_ab12cd", … } }   // 201

{ "tenant": { "id": "org_…", "tid": "acme-ventures", "name": "Acme Ventures", "status": "active" }, "apiKey": { "id": "key_…", "name": "…", "prefix": "…" } }

Admin

User management for support, admin and super-admin roles. Only a super-admin can grant or remove admin roles or act on an admin account, and the last super-admin can never be demoted. Every action is audited, including refused ones.

{ "users": [ … ], "total": 42 }

{ "userId": "usr_…", "role": "support" }

{ "userId": "usr_…", "banReason": "spam" }

{ "userId": "usr_…" }

{ "userId": "usr_…" }

{ "userId": "usr_…" }

{ "items": [{ "id": "aud_…", "action": "admin.role_change.success", … }], "nextCursor": "aud_…" }

Roles and permissions

Permissions are resource:action keys. Read the current user's with GET /v1/me/permissions. No role can impersonate users.

Tenants

A tenant is an organisation with an owner and members. The default tenant is UnityHUB (tid unityx): every UNX account joins it as a member when it is created, so apps can rely on at least one membership per user.

{
  "items": [
    {
      "role": "member",
      "joinedAt": "2026-09-26T08:00:00.000Z",
      "tenant": { "id": "org_…", "tid": "unityx", "slug": "unityx", "name": "UnityHUB", "status": "active" }
    }
  ]
}

Social sign-in

Google, Microsoft, Apple, GitHub, Facebook, LinkedIn and X are supported. A provider is live once its OAuth client is configured; GET /v1/providers lists those that are. The callback URL registered with each provider is:

https://auth.unx.ng/v1/auth/callback/{provider}   # e.g. …/callback/google

Account linking. When a social sign-in uses the same email as an existing UNX account, it links to that account automatically, but only if the provider confirms the email is verified and the UNX account's email is verified. Otherwise the user is sent back with ?error=account_not_linked. Signed-in users can also link or unlink providers with POST /v1/auth/link-social and POST /v1/auth/unlink-account.

Errors and limits

Authentication routes return { "code", "message" }. Platform routes under /v1 return { "error": { "code", "message", "requestId", "details" } }; quote requestId (also in the X-Request-Id header) when reporting a problem.