Auth Service API

End-user authentication for your auth apps lives at https://auth.ghayma.tech, not on the platform API. Every path is scoped by your app slug (app_id in the console):

https://auth.ghayma.tech/v1/{appSlug}/…

Credentials

• Public endpoints (register, login, refresh, password reset, OAuth start, code exchange, native sign-in) take no credential.
• Account endpoints (/me, change password, email change, 2FA management) take the end user’s access token: Authorization: Bearer <access_token>.
• Servers that forward end-user traffic send X-Ghayma-Server-Key together with X-Ghayma-Client-IP (both or neither) so rate limits apply to the real client. See Auth Integration.

Errors and rate limits

Every error is JSON: { "error": "<message>" }, with a machine-readable code on newer endpoints (invalid_request, invalid_grant, invalid_token, email_not_verified) and on every 429 (rate_limited), which also carries Retry-After in seconds.

Sessions

An access token works until it expires, or until the user’s sessions end: a password reset or change, a confirmed email change, a provider sign-in taking the account over, a replaced refresh token presented again, or the user being disabled. The service then refuses every refresh token issued before with 401, and every access token issued before with the 401 an expired one gets (403 while the user stays disabled). Pending second-factor challenges, a pending email change and an unspent one-time PKCE code stop working too. Tokens carry a sep claim naming the session generation they belong to; a backend that verifies them itself against the JWKS keeps accepting them until they expire. See Auth Integration → Ending every session.

Second factor

POST /login, POST /oauth/exchange and POST /oauth/id-token answer 200 with a session — or, when the app’s 2FA policy applies to the user, with a pending step and no tokens: TwoFARequired (finish at POST /2fa/verify) or TwoFAEnrollmentRequired (enrol at POST /2fa/totp/enroll and POST /2fa/totp/confirm). Check for two_fa_required / two_fa_enrollment_required before reading tokens. In the fragment flow (no code_challenge), the Google and GitHub callbacks carry the same step in the redirect fragment instead. See Auth Integration → Two-Factor Authentication.

Contract

The reference below is rendered from the live OpenAPI 3.0.3 document the service publishes. Download it as openapi.yaml  or openapi.json  to generate a client in any language or to import it into Postman or Insomnia.