M2M (Machine-to-Machine) Authentication

Machine-to-machine authentication allows your backend services, cron jobs, and automation scripts to securely call the ZewstID API without user interaction.

Overview

M2M authentication uses the OAuth 2.0 Client Credentials grant. Your service authenticates with a client ID and secret, and receives an access token scoped to specific permissions.

Copy
Your Service                    ZewstID API
    │                               │
    │  POST /oauth/token            │
    │  grant_type=client_credentials│
    │  client_id=xxx                │
    │  client_secret=yyy            │
    │  ─────────────────────────►   │
    │                               │
    │  { access_token: "eyJ..." }   │
    │  ◄─────────────────────────   │
    │                               │
    │  GET /api/v1/m2m/users        │
    │  Authorization: Bearer eyJ... │
    │  ─────────────────────────►   │
    │                               │
    │  { users: [...] }             │
    │  ◄─────────────────────────   │

Creating a Service Account

Via the Developer Portal

1. Navigate to Service Accounts in the left sidebar
2. Click Create Service Account
3. Enter a name and description
4. Select the scopes your service needs
5. Click Create — you'll receive a
   Copy

   clientId
   and
   Copy

   clientSecret

Important: Save the client secret immediately. It is only shown once.

Via the API

Copy
curl -X POST https://api.zewstid.com/api/v1/service-accounts \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Backend Service",
    "description": "Handles nightly user sync",
    "scopes": ["users:read", "users:write"]
  }'

Response:

Copy
{
  "id": "sa_abc123",
  "clientId": "sa-my-backend-service",
  "clientSecret": "zs_secret_xxxxx",
  "name": "My Backend Service",
  "scopes": ["users:read", "users:write"],
  "createdAt": "2026-02-20T10:00:00Z"
}

Getting an Access Token

Use the

grant to obtain an access token:

Copy
curl -X POST https://api.zewstid.com/api/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "sa-my-backend-service",
    "client_secret": "zs_secret_xxxxx",
    "scope": "users:read"
  }'

Response:

Copy
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "users:read"
}

Tokens expire after 1 hour by default. Your service should request a new token before the current one expires.

Scope System

Scopes control what your service account can access:

Request only the scopes your service needs. You can update scopes later via the portal or API.

M2M API Endpoints

Once you have an access token, use it to call the M2M API:

Node SDK Usage

The

SDK provides a class for M2M authentication:

Copy
import { ZewstIDServiceAccount } from '@zewstid/node';

const serviceAccount = new ZewstIDServiceAccount({
  domain: 'auth.zewstid.com',
  clientId: process.env.ZEWSTID_SA_CLIENT_ID!,
  clientSecret: process.env.ZEWSTID_SA_CLIENT_SECRET!,
  scopes: ['users:read', 'users:write'],
});

// Get a token (automatically cached and refreshed)
const token = await serviceAccount.getToken();

// Use the token
const res = await fetch('https://api.zewstid.com/api/v1/m2m/users', {
  headers: { Authorization: `Bearer ${token}` },
});
const users = await res.json();

The SDK handles token caching, automatic refresh, and retry logic.

Credential Rotation

Rotate your service account credentials periodically for security:

Copy
curl -X POST https://api.zewstid.com/api/v1/service-accounts/sa_abc123/rotate \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

Copy
{
  "clientId": "sa-my-backend-service",
  "clientSecret": "zs_secret_new_yyyyy",
  "rotatedAt": "2026-02-20T12:00:00Z"
}

The old secret is invalidated immediately. Update your service configuration with the new secret.

Rate Limits

M2M endpoints have the following rate limits:

Rate limit headers are included in every response:

Copy
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1708420800

Best Practices

1. Least privilege — Request only the scopes your service needs
2. Rotate credentials — Rotate secrets every 90 days
3. Cache tokens — Don't request a new token for every API call
4. Handle expiration — Check
   Copy

   expires_in
   and refresh before expiry
5. Secure storage — Store credentials in environment variables or a secrets manager, never in source code
6. Monitor usage — Check the audit log for unexpected access patterns

Next Steps

• Agent Authentication — Register AI agents with trust levels
• Delegation & A2A — Agent-to-agent token exchange
• Node.js SDK Reference —
  Copy

  ZewstIDServiceAccount
  class docs