Authentication

DGuard uses different authentication mechanisms depending on the flow of communication. OAuth2 is used for your requests to our API, while HMAC Signatures are used for our webhook notifications to your server.

API Requests (Client to DGuard)

Standard OAuth2 Client Credentials flow. You exchange your secret for a Bearer token used in subsequent API calls.

OAuth2 Bearer

Webhooks (DGuard to Client)

Directional security using HMAC-SHA256. You verify the signature DGuard sends to ensure the event is legitimate and untampered.

HMAC Signature

Authentication Flow

Your integration authenticates by exchanging your client credentials for a temporary access token. Here's the standard workflow:

Obtain Credentials

Get your client_id and client_secret via the DGuard Partner Portal.

Exchange for Token

Call POST /auth/token to receive a JWT access token.

Access API Resources

Include the Bearer token in the header of all subsequent requests.

Credentials

Your credentials identify your application and should be kept secure.

client_id

Unique public identifier for your application.

client_secret

Confidential key used to authorize token requests. Never expose this publicly.

Step 1: Get Access Token

To begin, request a temporary access token by providing your client credentials.

Request

bash

POST /auth/token

Headers

Content-Type: application/json

Body

json

{
  "grant_type": "client_credentials",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "scope": "fraud:read phishing:read vpn:manage"
}

Success Response (200 OK)

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "fraud:read phishing:read vpn:manage",
  "issued_at": "2025-01-19T15:30:00Z"
}

Step 2: Authenticated Requests

Include your access token in the Authorization header using the Bearer scheme.

Header Format

Authorization: Bearer <access_token>

Example Request

bash

curl -X GET "{base_url}/fraud/transactions" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Complete Integration Example

javascript

// Step 1: Get access token
const tokenResponse = await fetch("{base_url}/auth/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    grant_type: "client_credentials",
    client_id: "your_client_id",
    client_secret: "your_client_secret",
    scope: "fraud:read fraud:write"
  })
});
const { access_token } = await tokenResponse.json();

// Step 2: Make API requests using the Bearer token
const apiResponse = await fetch("{base_url}/fraud/transactions", {
  headers: {
    "Authorization": `Bearer ${access_token}`,
    "Content-Type": "application/json"
  }
});

Token Lifecycle

Access tokens expire after 1 hour (3600 seconds). Implement proactive token refresh to avoid request failures.

Proactive Refresh

Refresh when 5 minutes remain. Check issued_at + expires_in.

On 401 Response

Refresh token immediately and retry the request once. If retry fails, re-authenticate.

No Refresh Tokens

OAuth2 refresh tokens are not used. Simply call /auth/token again.

Token Manager Example

typescript

class TokenManager {
  private token: string | null = null;
  private expiresAt: number = 0;
  
  async getToken(): Promise<string> {
    // Refresh if expired or within 5 minutes of expiry
    const bufferMs = 5 * 60 * 1000;
    if (!this.token || Date.now() >= this.expiresAt - bufferMs) {
      await this.refresh();
    }
    return this.token!;
  }
  
  private async refresh(): Promise<void> {
    const response = await fetch("{base_url}/auth/token", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        grant_type: "client_credentials",
        client_id: process.env.DGUARD_CLIENT_ID,
        client_secret: process.env.DGUARD_CLIENT_SECRET
      })
    });
    
    const data = await response.json();
    this.token = data.access_token;
    this.expiresAt = Date.now() + (data.expires_in * 1000);
  }
  
  async fetchWithAuth(url: string, options: RequestInit = {}): Promise<Response> {
    const token = await this.getToken();
    const response = await fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        "Authorization": `Bearer ${token}`
      }
    });
    
    // Retry once on 401
    if (response.status === 401) {
      await this.refresh();
      return fetch(url, {
        ...options,
        headers: {
          ...options.headers,
          "Authorization": `Bearer ${this.token}`
        }
      });
    }
    
    return response;
  }
}

Rate Limits

Rate limits are enforced per application (Client ID). For detailed information on tiers, headers, and retry strategies, please see the Security & Compliance page.

Rate Limit Headers

bash

X-RateLimit-Limit-Minute: 1000
X-RateLimit-Remaining-Minute: 999
X-RateLimit-Reset: 1705244400

Security Recommendations

✓

Store client_secret securely (vault, env vars)

✓

Implement credential rotation every 90 days

✓

Use HTTPS exclusively

✓

Implement retry with exponential backoff

✓

Log and monitor all API accesses

✓

Cache access tokens and refresh before expiry (expires_in: 3600s)