Authentication

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

Token Format

Access tokens are RS256-signed JWTs containing your user identity and organization (tenant) context. The gateway validates tokens using JWKS (JSON Web Key Set) from the auth service.

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

Login

POST

/auth/login

Authenticate and receive tokens.

Email/password loginbash

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 loginbash

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

Responsejson

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

Signup

POST

/auth/signup

Create a new user account.

Requestbash

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.

Requestbash

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.

Requestbash

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.

Requestbash

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

Responsejson

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

Proactive Refresh

Refresh the token before it expires (e.g., when less than 60 seconds remain). This avoids interrupted API calls due to expired tokens.

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.

Requestbash

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.

Requestbash

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.

Requestbash

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.

Requestbash

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.

Requestbash

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 PATbash

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

Treat PATs like passwords

A PAT grants the same access as the user who created it. Store them in your secret manager, never in source control, and rotate periodically.

Organization Context

Most JWTs include the active organization in the tenant-id ororg_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)