Documentation

Authentication

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

Overview

The authentication flow works as follows:

  1. Authenticate via login or SSO to receive an access token and refresh token
  2. Include the access token in the Authorization header for all API requests
  3. When the access token expires, use the refresh token to obtain a new one
  4. 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

ProviderMethodDescription
Email/PasswordemailStandard email and password with OTP verification
GooglegoogleOAuth 2.0 with Google accounts
GitHubgithubOAuth 2.0 with GitHub accounts
SAMLsamlEnterprise 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>"

Request Headers

HeaderValueRequired
AuthorizationBearer <access_token>Yes (all endpoints except /auth/*)
Content-Typeapplication/jsonYes (for POST/PUT/PATCH requests)