API Authentication#

All Novaza API requests must be authenticated with a JWT access token issued by Novaza SSO at id.novaza.ai. The token is carried in the Authorization: Bearer <token> header on every request to the Novaza Gateway (api.novaza.ai).

Individual products (Office, Desk, Pulse) are served from their own domains and accept access tokens obtained through the same Novaza SSO authorization flow, with a product-scoped audience.

Overview#

A user signs in at id.novaza.ai (directly or via an OAuth2 authorization redirect from your application).
Novaza SSO issues a JWT access token (short-lived) and refresh token (longer-lived).
Your client calls https://api.novaza.ai/... with Authorization: Bearer <access_token>.
When the access token expires, exchange the refresh token for a new access token at the SSO token endpoint.

OAuth2 Authorization Code Flow#

Use this flow for user-facing third-party applications that act on behalf of a signed-in Novaza user.

1. Register an OAuth2 Client#

Administrators register OAuth2 clients in Novaza SSO. For each client you receive:

Client ID
Client Secret (for confidential clients)
One or more registered redirect URIs

2. Redirect the User to the Authorization Endpoint#

GET https://id.novaza.ai/realms/novaza/protocol/openid-connect/auth
    ?client_id=YOUR_CLIENT_ID
    &redirect_uri=YOUR_REDIRECT_URI
    &response_type=code
    &scope=openid profile email
    &state=RANDOM_STATE

The user authenticates at Novaza SSO and is redirected back to your redirect URI with a code parameter.

3. Exchange the Code for Tokens#

POST /realms/novaza/protocol/openid-connect/token HTTP/1.1
Host: id.novaza.ai
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=YOUR_REDIRECT_URI

The response contains:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "refresh_token": "eyJhbGciOi...",
  "refresh_expires_in": 1800,
  "token_type": "Bearer",
  "scope": "openid profile email"
}

4. Call the Novaza Gateway#

GET /api/v1/billing/subscriptions HTTP/1.1
Host: api.novaza.ai
Authorization: Bearer eyJhbGciOi...
Accept: application/json

5. Refresh the Access Token#

When the access token expires, exchange the refresh token for a new one:

POST /realms/novaza/protocol/openid-connect/token HTTP/1.1
Host: id.novaza.ai
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Service-to-Service (Client Credentials)#

For backend integrations that do not act on behalf of a specific user, a client credentials flow is supported for confidential clients that have been granted the appropriate service role. Contact support to enable service accounts on your workspace.

POST /realms/novaza/protocol/openid-connect/token HTTP/1.1
Host: id.novaza.ai
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Token Validation#

The Novaza Gateway validates each JWT by:

Verifying the signature against the Novaza SSO JWKS (id.novaza.ai/realms/novaza/protocol/openid-connect/certs)
Checking the iss, aud, and exp claims
Resolving the tenant from the token claims and applying per-tenant rate limiting

Invalid or expired tokens result in 401 Unauthorized.

Security Best Practices#

Never commit client secrets to version control. Use environment variables or a secrets manager.
Use short access token lifetimes and refresh frequently.
Store refresh tokens encrypted at rest on the server side.
Use the minimum required scope when requesting authorization.
Monitor sign-ins via the SSO admin audit log to detect unexpected activity.