Authentication API

The Zero API uses JWT (JSON Web Tokens) for authentication. This guide covers obtaining tokens, refreshing sessions, and SSO integration.

Authentication Methods

Method Use Case Token Lifetime
Password Login User authentication 24 hours
API Keys Service accounts, automation 90 days (configurable)
SSO (OIDC/SAML) Enterprise SSO Session-based
Device Certificates Device authentication 1 year

Password Login

POST /api/v1/auth/login

Authenticate with email and password to obtain an access token.

Request

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "admin@example.com",
  "password": "your-password"
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "expires_in": 86400,
  "token_type": "Bearer",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@example.com",
    "name": "Admin User",
    "role": "admin",
    "organization_id": "org-123"
  }
}

Error Responses

HTTP/1.1 401 Unauthorized
{
  "code": 401,
  "message": "invalid credentials"
}

HTTP/1.1 429 Too Many Requests
{
  "code": 429,
  "message": "too many login attempts, try again in 15 minutes"
}

Multi-Factor Authentication

If MFA is enabled, the login response includes a challenge:

HTTP/1.1 200 OK
{
  "mfa_required": true,
  "mfa_token": "mfa_temp_token_123",
  "mfa_methods": ["totp", "webauthn"]
}

POST /api/v1/auth/mfa/verify

POST /api/v1/auth/mfa/verify
Content-Type: application/json

{
  "mfa_token": "mfa_temp_token_123",
  "method": "totp",
  "code": "123456"
}

Token Refresh

POST /api/v1/auth/refresh

Exchange a refresh token for a new access token.

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "bmV3IHJlZnJlc2ggdG9rZW4...",
  "expires_in": 86400
}
Token Rotation: Refresh tokens are single-use. A new refresh token is issued with each refresh request.

Logout

POST /api/v1/auth/logout

Invalidate the current access token and refresh token.

POST /api/v1/auth/logout
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

API Keys

Create long-lived API keys for automation and service accounts.

POST /api/v1/auth/api-keys

POST /api/v1/auth/api-keys
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "name": "CI/CD Integration",
  "scopes": ["devices:read", "policies:read"],
  "expires_in_days": 90
}

Response

{
  "id": "key_abc123",
  "name": "CI/CD Integration",
  "key": "wv_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ123456",
  "scopes": ["devices:read", "policies:read"],
  "created_at": "2026-02-12T10:30:00Z",
  "expires_at": "2026-05-13T10:30:00Z"
}
Important: The full API key is only shown once. Store it securely.

Available Scopes

Scope Description
devices:read List and view devices
devices:write Enroll, update, wipe devices
policies:read View policies
policies:write Create, update, delete policies
users:read View users
users:write Manage users
audit:read View audit logs
admin Full administrative access

SSO Integration

OpenID Connect (OIDC)

Configure OIDC SSO with providers like Okta, Azure AD, or Google Workspace.

Initiate SSO

GET /api/v1/auth/sso/oidc/authorize?
  client_id=zero&
  redirect_uri=https://console.zero.io/callback&
  scope=openid+profile+email&
  state=random_state_string

Handle Callback

POST /api/v1/auth/sso/oidc/callback
Content-Type: application/json

{
  "code": "authorization_code_from_idp",
  "state": "random_state_string"
}

SAML 2.0

SAML SSO is available for Enterprise customers.

# SAML metadata endpoint
GET /api/v1/auth/sso/saml/metadata

# SAML assertion consumer service
POST /api/v1/auth/sso/saml/acs

JWT Token Structure

Zero JWTs contain the following claims:

{
  "sub": "user_id",
  "org": "organization_id",
  "role": "admin",
  "scopes": ["devices:read", "policies:write"],
  "iat": 1707734400,
  "exp": 1707820800,
  "iss": "https://api.zero.io"
}

Using Tokens

Include the access token in the Authorization header:

curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  https://api.zero.io/api/v1/devices

Security Best Practices

  • Store tokens securely - Never expose tokens in client-side code or logs
  • Use short-lived tokens - Access tokens expire in 24 hours
  • Rotate refresh tokens - Refresh tokens are single-use
  • Use scoped API keys - Grant minimum required permissions
  • Enable MFA - Require MFA for administrative accounts
  • Monitor for abuse - Review audit logs for suspicious activity

Next Steps