Authentication

Every request to the npayload API must be authenticated. The SDK handles this automatically. If you are integrating without the SDK, this page explains how to authenticate using direct HTTP calls.

Using the SDK (recommended)

The SDK handles authentication, token management, and request signing automatically. You provide your credentials and the SDK does the rest.

import { NPayloadAuth, NPayloadClient } from '@npayload/node';

const auth = new NPayloadAuth({
  clientId: process.env.NPAYLOAD_CLIENT_ID!,   // oac_...
  hmacSecret: process.env.NPAYLOAD_HMAC_SECRET!,
});

const npayload = new NPayloadClient({ auth });

That is it. The SDK manages token exchange, automatic refresh, and request signing. You never need to handle tokens directly.

Getting your credentials

1. Log in to admin.npayload.com
2. Select your Organisation and App
3. Navigate to Machine Credentials and register a new client
4. Copy your Client ID (starts with oac_) and HMAC Secret

Direct HTTP authentication

If you are not using the SDK, authenticate with the following steps.

Step 1: Request an access token

curl -X POST https://api.npayload.com/oauth/token \
  -H "Content-Type: application/json" \
  -H "DPoP: <dpop_proof_jwt>" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "oac_your_client_id",
    "client_secret": "<hmac_signature>"
  }'

Step 2: Use the token in API calls

curl -H "Authorization: DPoP <access_token>" \
  -H "DPoP: <dpop_proof_for_this_request>" \
  https://api.npayload.com/v1/channels

Scopes

Request only the scopes your application needs.

Best practices

• Store credentials in a secret vault (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, or similar). Never hardcode secrets in your source code
• Use the SDK whenever possible. It handles token rotation automatically
• Rotate your HMAC secret regularly via the dashboard
• Request only the scopes your application needs

Next steps