Authentication

JWT-based authentication for the ZopNight API. Login, signup, SAML SSO, token refresh, PATs, and request headers.

ZopNight uses JWT-based authentication. All API requests (except auth endpoints) require a valid access token.

Overview

The authentication flow works as follows:

Authenticate via login or SSO to receive an access token and refresh token
Include the access token in the Authorization header for all API requests
When the access token expires, use the refresh token to obtain a new one
The gateway validates the JWT, extracts your organization context, and routes the request

Authentication Providers

Provider	Method	Description
Email/Password	`email`	Standard email and password with OTP verification
Google	`google`	OAuth 2.0 with Google accounts
GitHub	`github`	OAuth 2.0 with GitHub accounts
SAML	`saml`	Enterprise SSO via SAML 2.0 identity providers

POST/auth/login

Authenticate and receive tokens.

Email/password login · bash

curl -X POST https://zopnight.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{
  "email": "user@company.com",
  "password": "your-password",
  "provider": "email"
}'

Google OAuth login · bash

curl -X POST https://zopnight.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{
  "provider": "google",
  "token": "<google-oauth-id-token>"
}'

Response · json

{
"data": {
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
  "tenants": [
    {
      "id": "org_abc123",
      "name": "Acme Corp"
    }
  ],
  "user": {
    "email": "user@company.com",
    "name": "Jane Doe"
  }
}
}

POST/auth/signup

Create a new user account.

Request · bash

curl -X POST https://zopnight.com/api/auth/signup \
-H "Content-Type: application/json" \
-d '{
  "email": "newuser@company.com",
  "password": "secure-password",
  "name": "Jane Doe"
}'

After signup, verify your email using the OTP sent to your inbox.

Email Verification

POST/auth/email/verify

Request a verification OTP.

Request · bash

curl -X POST https://zopnight.com/api/auth/email/verify \
-H "Content-Type: application/json" \
-d '{ "email": "user@company.com" }'

PATCH/auth/email/otp/validate

Validate the OTP code.

Request · bash

curl -X PATCH https://zopnight.com/api/auth/email/otp/validate \
-H "Content-Type: application/json" \
-d '{
  "email": "user@company.com",
  "otp": "123456"
}'

Token Refresh

Access tokens are short-lived. Use the refresh token to obtain a new access token before expiry.

POST/auth/refresh

Exchange a refresh token for a new access token.

Request · bash

curl -X POST https://zopnight.com/api/auth/refresh \
-H "Content-Type: application/json" \
-d '{
  "refreshToken": "dGhpcyBpcyBhIHJlZnJl...",
  "tenantID": "org_abc123"
}'

Response · json

{
"data": {
  "accessToken": "eyJhbGciOiJSUzI1NiIs...(new token)",
  "refreshToken": "bmV3IHJlZnJlc2ggdG9r..."
}
}

SAML SSO

Enterprise organizations can configure SAML 2.0 single sign-on with their identity provider.

POST/auth/saml/initiate

Begin a SAML authentication flow.

Request · bash

curl -X POST https://zopnight.com/api/auth/saml/initiate \
-H "Content-Type: application/json" \
-d '{ "email": "user@enterprise.com" }'

Returns a redirect URL to your organization's identity provider. After authentication, the IdP redirects back with a SAML assertion that is exchanged for JWT tokens.

Create Organization

POST/auth/v2/organisation

Create a new organization for your account.

Request · bash

curl -X POST https://zopnight.com/api/auth/v2/organisation \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{ "name": "My Company" }'

Password Reset

POST/auth/password/forget

Initiate a password reset.

Request · bash

curl -X POST https://zopnight.com/api/auth/password/forget \
-H "Content-Type: application/json" \
-d '{ "email": "user@company.com" }'

POST/auth/password/reset

Complete the password reset.

Request · bash

curl -X POST https://zopnight.com/api/auth/password/reset \
-H "Content-Type: application/json" \
-d '{
  "email": "user@company.com",
  "otp": "123456",
  "newPassword": "new-secure-password"
}'

Logout

POST/auth/logout

Invalidate the current session.

Request · bash

curl -X POST https://zopnight.com/api/auth/logout \
-H "Authorization: Bearer <token>"

Personal Access Tokens (PAT)

For CI pipelines, scripts, and other non-interactive clients, ZopNight supports Personal Access Tokens. PATs use the same Authorization: Bearer header as JWT access tokens but are validated against the auth service directly rather than through JWKS — they don't expire on the same schedule as user JWTs.

Property	Value
Prefix	`zn_pat_` followed by an opaque secret
Where to use	`Authorization: Bearer zn_pat_...`
Created from	The ZopNight UI under Settings → Personal Access Tokens
Scope	Inherits the creating user's role and permissions

Using a PAT · bash

curl https://zopnight.com/api/resources \
-H "Authorization: Bearer zn_pat_xxxxxxxxxxxxxxxxxxxxxxxx"

Organization Context

Most JWTs include the active organization in the tenant-id or org_id claim, and that value is used to scope every request. If a token does not carry an org claim (for example, when a user belongs to multiple orgs and the client wants to override the default), pass an explicit header:

Header	Value	When to use
`X-Org-Id`	The target organization's ID	Override the JWT's default org, or supply org context for tokens that lack one.

Unauthenticated Endpoints

A small number of endpoints intentionally bypass JWT validation. They use other mechanisms (HMAC signatures, body-carried JWTs, or no auth at all):

Endpoint	Authentication	Purpose
`POST /webhooks/github`	HMAC-SHA256 signature in `X-Hub-Signature-256`	GitHub push & PR webhooks for the deploy pipeline
`POST /build-callbacks/{revisionID}`	JWT carried in the request body, signed with the build callback secret	Build runner reports back when an image is ready
`GET /.well-known/openid-configuration`	Public	OIDC discovery (used by Azure Workload Identity Federation)
`GET /.well-known/jwks.json`	Public	JSON Web Key Set for verifying ZopNight-issued tokens
`POST /auth/*`	Varies (login, signup, refresh)	Authentication flows themselves

Request Headers

Header	Value	Required
`Authorization`	`Bearer <access_token \| PAT>`	Yes (all endpoints except those listed above)
`X-Org-Id`	An organization ID	Optional — overrides the org claim in the JWT
`Content-Type`	`application/json`	Yes (for POST/PUT/PATCH requests)

Overview

Authentication Providers

Login

Signup

Email Verification

Token Refresh

SAML SSO

Create Organization

Password Reset

Logout

Personal Access Tokens (PAT)

Organization Context

Unauthenticated Endpoints

Request Headers