Authentication

Every request to the ITSM Automation API must be authenticated. The API supports three authentication methods: JWT bearer tokens (recommended), API keys for service integrations, and OAuth2/SSO for enterprise identity providers. All tokens use RS256 asymmetric signing with 2048-bit RSA keys.

Before you can authenticate, you need an ITSM Automation account. Head to the quickstart guide to create your account and obtain your first credentials.

POST/v1/auth/login

JWT bearer token authentication

The recommended way to authenticate with the ITSM Automation API is using JWT bearer tokens. After logging in with your credentials, you receive an access token (15-minute TTL) and a refresh token (7-day TTL). Include the access token in the Authorization header of every request.

The API also accepts tokens from the itsm_auth_token httpOnly cookie, which is set automatically during browser-based login flows.

Token payload

Name
sub
Type
string
Description
Unique identifier for the authenticated user.
Name
email
Type
string
Description
Email address of the authenticated user.
Name
organizationId
Type
string
Description
The tenant organization the user belongs to.
Name
role
Type
string
Description
The user's assigned role (e.g., service_desk_agent, tenant_admin).
Name
sessionId
Type
string
Description
Unique identifier for the current session, used for session management and revocation.
Name
permissions
Type
string[]
Description
Array of granted permissions in resource:action:scope format.
Name
jti
Type
string
Description
Unique JWT identifier used for token revocation and replay prevention.

Request

POST

/v1/auth/login

curl -X POST https://api.itsm.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "agent@acme-corp.com",
    "password": "your-secure-password"
  }'

Response

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3Jf...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3Jf...",
  "expiresIn": 900,
  "tokenType": "Bearer",
  "user": {
    "id": "usr_01HQ3K5V8NXGP2T0FWZR9SJCMA",
    "email": "agent@acme-corp.com",
    "role": "service_desk_agent",
    "organizationId": "org_01HQ3K5V8NXGP2T0FWZR9SJCMB"
  }
}

GET/v1/tickets

Using bearer tokens

Once you have an access token, include it in the Authorization header of every API request. The token is valid for 15 minutes. When it expires, use the refresh token to obtain a new access token without re-entering credentials.

The API reads the token from two sources, checked in order:

Authorization header (recommended) -- Authorization: Bearer {access_token}
httpOnly cookie -- itsm_auth_token, set automatically during browser login

Request

GET

/v1/tickets

curl https://api.itsm.example.com/v1/tickets \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "X-Tenant-Slug: acme-corp"

Response

{
  "data": [
    {
      "id": "tkt_01HQ3K6A9BMXP4R2CWZY7TNDEF",
      "title": "VPN connectivity issue",
      "status": "open",
      "priority": "high",
      "assigneeId": "usr_01HQ3K5V8NXGP2T0FWZR9SJCMA",
      "createdAt": "2026-02-24T10:30:00Z"
    }
  ],
  "hasMore": true,
  "cursor": "eyJpZCI6InRrdF8wMUhR..."
}

POST/v1/auth/refresh

Refreshing tokens

Access tokens expire after 15 minutes. Use the refresh token endpoint to obtain a new access token without requiring the user to log in again. Refresh tokens are valid for 7 days and use sliding expiration -- each successful refresh extends the 7-day window.

Refresh tokens are single-use. Each refresh request returns a new refresh token, and the previous one is immediately invalidated. This rotation strategy limits the window of exposure if a refresh token is compromised.

Request

POST

/v1/auth/refresh

curl -X POST https://api.itsm.example.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3Jf..."
  }'

Response

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3Jf...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJuZXdSZWZyZXNo...",
  "expiresIn": 900,
  "tokenType": "Bearer"
}

GET/v1/tickets

API key authentication

API keys are intended for server-to-server integrations, CI/CD pipelines, and automated workflows where interactive login is not possible. Each API key is scoped to specific permissions and subject to rate limiting.

API keys use the format tnt_<timestamp><random><hash> and are tied to a specific organization. Include the key in the X-API-Key header.

API key properties

Name
id
Type
string
Description
Unique identifier for the API key.
Name
name
Type
string
Description
Human-readable name for identifying the key's purpose.
Name
key
Type
string
Description
The API key value in tnt_<timestamp><random><hash> format. Only shown once at creation time.
Name
permissions
Type
string[]
Description
Scoped permissions in resource:action:scope format.
Name
rateLimitPerMinute
Type
integer
Description
Maximum number of requests allowed per minute for this key.
Name
expiresAt
Type
timestamp
Description
Optional expiration date. Null means the key does not expire.

Request

GET

/v1/tickets

curl https://api.itsm.example.com/v1/tickets \
  -H "X-API-Key: tnt_17089452801a2b3c4d5e6f_8a9b0c1d2e" \
  -H "X-Tenant-Slug: acme-corp"

Response

{
  "data": [
    {
      "id": "tkt_01HQ3K6A9BMXP4R2CWZY7TNDEF",
      "title": "VPN connectivity issue",
      "status": "open",
      "priority": "high",
      "createdAt": "2026-02-24T10:30:00Z"
    }
  ],
  "hasMore": true,
  "cursor": "eyJpZCI6InRrdF8wMUhR..."
}

API keys are shown only once at creation time. Store them securely in a secrets manager. If a key is compromised, revoke it immediately from the ITSM dashboard under Settings » API Keys.

GET/v1/auth/sso/:provider

OAuth2 / SSO

For enterprise environments, the ITSM Automation API supports single sign-on through OAuth2 and SAML 2.0 identity providers. All OAuth2 flows use PKCE (Proof Key for Code Exchange) for security.

Supported providers

Name
azure-ad
Type
OAuth2 / OIDC
Description
Microsoft Azure Active Directory. Supports automatic user provisioning via SCIM.
Name
google
Type
OAuth2 / OIDC
Description
Google Workspace. Maps Google groups to ITSM roles.
Name
saml
Type
SAML 2.0
Description
Any SAML 2.0 compliant identity provider (Okta, OneLogin, PingFederate, etc.).
Name
oidc
Type
OpenID Connect
Description
Generic OIDC provider for custom identity solutions.

SSO login flow

Redirect the user to /v1/auth/sso/:provider with a PKCE code_challenge.
The user authenticates with their identity provider.
The ITSM API receives the callback and exchanges the authorization code.
The API returns JWT tokens (same format as password login).

SSO Initiation

# Step 1: Generate PKCE verifier and challenge
CODE_VERIFIER=$(openssl rand -base64 32 | tr -dc 'a-zA-Z0-9' | head -c 43)
CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | \
  openssl dgst -sha256 -binary | base64 | tr '+/' '-_' | tr -d '=')

# Step 2: Redirect user to SSO endpoint
curl -G https://api.itsm.example.com/v1/auth/sso/azure-ad \
  -d "code_challenge=$CODE_CHALLENGE" \
  -d "code_challenge_method=S256" \
  -d "redirect_uri=https://app.acme-corp.com/auth/callback" \
  -d "state=$(openssl rand -hex 16)"

Response

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
  "expiresIn": 900,
  "tokenType": "Bearer",
  "user": {
    "id": "usr_01HQ3K5V8NXGP2T0FWZR9SJCMA",
    "email": "agent@acme-corp.com",
    "role": "service_desk_agent",
    "organizationId": "org_01HQ3K5V8NXGP2T0FWZR9SJCMB",
    "ssoProvider": "azure-ad"
  }
}

POST/v1/auth/mfa/verify

Multi-factor authentication

When MFA is enabled for a user account, the login endpoint returns a mfaRequired challenge instead of tokens. The client must then verify the MFA challenge before receiving access tokens.

Supported MFA methods

Name
totp
Type
TOTP
Description
Time-based one-time passwords via authenticator apps (Google Authenticator, Authy, 1Password, etc.).
Name
webauthn
Type
WebAuthn / FIDO2
Description
Hardware security keys and platform biometrics (YubiKey, Touch ID, Windows Hello).
Name
backup_codes
Type
Recovery
Description
Single-use 8-character recovery codes generated during MFA setup. Each user receives 10 codes.

MFA Flow

curl -X POST https://api.itsm.example.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@acme-corp.com",
    "password": "your-secure-password"
  }'
# Returns 202 with mfaRequired: true

MFA challenge response (202)

{
  "mfaRequired": true,
  "mfaToken": "mfa_01HQ3K7B2NXGP2T0FWZR9SJCMC",
  "allowedMethods": ["totp", "webauthn", "backup_codes"],
  "expiresIn": 300
}

MFA verification success

{
  "accessToken": "eyJhbGciOiJSUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
  "expiresIn": 900,
  "tokenType": "Bearer"
}

Role-based access control (RBAC)

The ITSM Automation API enforces role-based access control on every request. Each user is assigned a role that determines their base permissions. Permissions follow the resource:action:scope format.

Roles

Name
end_user
Type
role
Description
Can create and view their own tickets. Cannot access other users' data or administrative functions.
Name
service_desk_agent
Type
role
Description
Can view and manage tickets assigned to them or their team. Can update ticket status, priority, and classification.
Name
service_desk_manager
Type
role
Description
Full access to all tickets within the organization. Can manage agent assignments, view reports, and configure SLA policies.
Name
tenant_admin
Type
role
Description
Complete administrative access for a single tenant. Can manage users, roles, API keys, SSO configuration, and organization settings.
Name
super_admin
Type
role
Description
Platform-level administrator with access across all tenants. Reserved for platform operators.

Permission format

Permissions use the pattern resource:action:scope where the scope determines the breadth of access.

Name
tickets:create:own
Type
permission
Description
Create tickets attributed to the authenticated user.
Name
tickets:read:team
Type
permission
Description
Read tickets assigned to anyone on the user's team.
Name
tickets:update:all
Type
permission
Description
Update any ticket within the organization.
Name
users:manage:all
Type
permission
Description
Create, update, and deactivate user accounts across the organization.
Name
api_keys:manage:own
Type
permission
Description
Create and revoke API keys scoped to the authenticated user.
Name
reports:read:all
Type
permission
Description
Access all reporting and analytics data within the organization.

Permissions are included in the JWT payload. If a user's role changes, their current access token continues to carry the old permissions until it expires (15 minutes max). For immediate revocation, use the session invalidation endpoint.

Multi-tenancy

The ITSM Automation API is multi-tenant by design. Tenant isolation is enforced at every layer: JWT tokens contain the organizationId claim, and all database queries are scoped to the authenticated tenant.

For API key requests or cross-tenant operations, include the X-Tenant-Slug header to specify the target organization.

Tenant resolution order

organizationId claim from the JWT token
X-Tenant-Slug request header (API key authentication)
Subdomain extraction from the Origin header (browser-based flows)

Multi-tenant requests

# organizationId is embedded in the JWT
curl https://api.itsm.example.com/v1/tickets \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Session management

Sessions are persisted in PostgreSQL with an active cache layer in Redis. The API supports device fingerprinting and sliding expiration to balance security with user convenience.

Name
sessionId
Type
string
Description
Unique session identifier included in every JWT. Used for selective session revocation.
Name
deviceFingerprint
Type
string
Description
Browser or device fingerprint collected during login. Anomalous fingerprint changes trigger re-authentication.
Name
slidingExpiration
Type
boolean
Description
When enabled, each authenticated request extends the session lifetime. Disabled by default for super_admin accounts.

Revoking sessions

Users can revoke individual sessions or all active sessions. Tenant admins can revoke sessions for any user within their organization.

Session revocation

curl -X POST https://api.itsm.example.com/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Response

{
  "revoked": true,
  "sessionsTerminated": 3,
  "message": "All active sessions have been revoked."
}

Using the SDK

If you use the official ITSM Automation SDK, token management is handled automatically. The SDK stores tokens securely, refreshes expired access tokens using the refresh token, and retries failed requests after re-authentication.

import { ItsmClient } from '@itsm-automation/sdk'

// The SDK handles token refresh and retry automatically
const client = new ItsmClient({
  email: 'agent@acme-corp.com',
  password: 'your-secure-password',
})

// Or authenticate with an API key for server-to-server integrations
const serviceClient = new ItsmClient({
  apiKey: 'tnt_17089452801a2b3c4d5e6f_8a9b0c1d2e',
  tenantSlug: 'acme-corp',
})

// All requests are authenticated automatically
const tickets = await client.tickets.list({ status: 'open' })

Get started with the quickstart guide

What's next?

Now that you understand how authentication works, here are some resources to continue with:

Quickstart guide -- Set up your environment and make your first API request
Tickets endpoint -- Create, triage, and manage IT service tickets
Error handling -- Understand authentication error codes like 401 Unauthorized and 403 Forbidden