Authentication
The API uses OAuth 2.0 Bearer tokens by our OAuth 2.0 authorization server (RS256-signed JWTs).
Use an OAuth 2.0 Bearer token by our OAuth 2.0 authorization server (RS256-signed JWTs) to authenticate protected API requests. Every protected endpoint expects an Authorization: Bearer <bearer-token> header.
Ways to obtain a token
- Password login — Call
POST /loginwith a JSON body containingemail,password, andrememberMe. The response includestoken(a Passport access token), the user's company context, location count, and branding theme. (Login) - SSO — JumpCloud (OIDC) — Start the browser flow with the authorization redirect. After the JumpCloud redirect and callback, call
GET /auth/sso/exchangeto redeem the one-time code for a token. (SSO — Review Management login (OAuth 2.0) / SSO — JumpCloud handoff) - Discover (optional, pre-login) — Call
POST /auth/discoverwith an email address to determine whether the account supports password login, SSO, or both. This endpoint does not reveal whether the email address exists (no account enumeration). (Discover auth methods)
Using the token
Send it on every protected call:
Authorization: Bearer <bearer-token>The following route groups use the Passport authentication guard:
| Prefix | Who | Token context |
|---|---|---|
/admin/* | Platform super-admin | admin user |
/partner/* | Partner admin (hipages service / sales teams) | Agency- or partner-level access_token |
/account/* | Account and location users, plus current-user self-service (dashboards and widgets formerly under /brand/*) | Account- or account-level access_token, scoped to its partner |
/sso/* | OAuth client management | super-admin |
Account-owner impersonation token
Call POST /partner/account-owner/token to mint a Passport personal access token issued as an account owner (formerly POST /partner/brand-owner/token). The collection stores the token as the impersonation token for requests that must run in the account's context.
Token lifecycle
- Access tokens and personal access tokens expire 1 day after issue.
- Refresh tokens are valid for 30 days.
- Verify:
GET /verify-token(Verify token) echoes the authenticated user when the token is still valid. - Revoke / logout:
GET /logout(Logout) deletes the current token server-side.
Public vs protected
Only a small set of endpoints are public (No Auth): login, email-OTP verify/resend, the signup wizard, auth discovery, SSO redirect/callback/exchange, pre-login branding and reference lookups (plans, feature-options, countries/states/cities, white-label resolver), campaign tracking + QR landing pages, and provider webhooks (Mandrill, Bandwidth, ReviewData — each verified by its own signature or token). Every state-changing (write) endpoint requires a valid OAuth bearer token.
Before you begin
- Obtain a bearer token and send it in the
Authorizationheader. Endpoints that do not require a token identify themselves on their own pages. - Identify each record your request targets. Every endpoint page lists the required IDs.
Errors
| Status | Meaning |
|---|---|
401 | The bearer token is missing, expired, or invalid. |
403 | The token is valid, but the record is outside your account. |
422 | The request failed validation; the response identifies the invalid fields. |
500 | An unexpected server error occurred. |
Individual endpoints may return more; each page lists its own.
Sections
Endpoints
POST — Authenticates an email/password credential and, on success, issues a Passport bearer token plus the user, company, theme, white-label and (for account companies) plan context.
GET — Validates the supplied Passport bearer token and restores the SPA session. Returns the authenticated user, company, theme, white-label, and, for account companies, plan context.
GET — Revokes the caller's current Passport access token and records the logout. Deletes the active token, stamps logout_time on the user's latest RsAuthEvent, and writes an AUTH_LOGOUT audit log.
POST — Verify the email OTP previously sent for a forgot-password / change-password / signup flow.
POST — Resend an email OTP for a change-password / forgot-password / signup flow.
POST — Reset the authenticated user's password to the supplied value, revokes all of their existing tokens, and returns a fresh access token.
POST — Start an authenticated password change: verifies the current password, then emails a change_password OTP rather than changing the password directly.
Updated 15 days ago