Authentication

DGuard uses JWT Bearer token authentication. Authenticate once to receive a short-lived access token and a long-lived refresh token, then send the access token on every request.

Authentication Flow Overview

Authentication is token-based. You exchange your credentials for a JSON Web Token (JWT), then present that token in the Authorization header of subsequent calls. There is no separate API-key header — the Bearer token is the single credential for API requests.

Authenticate

Call POST /api/auth/login with your credentials. Social and biometric sign-in are also supported.

Receive Tokens

Get back an access_token (short-lived JWT) and a refresh_token.

Call the API

Send Authorization: Bearer <access_token> on every request. Refresh the token when it expires.

One credential per request

Every request (except the auth endpoints themselves) requires the JWT access token in the Authorization: Bearer header. Tokens are signed by DGuard and expire, so they should be refreshed rather than stored long-term.

Tokens

A successful authentication returns two tokens, each with a distinct role:

access_token

Sent on every request

A short-lived JWT. Include it as Authorization: Bearer <access_token> on all API calls. When it expires, use the refresh token to obtain a new one.

refresh_token

For token renewal

A long-lived token used only to obtain a new access token via POST /api/auth/refresh. Store it securely and never expose it publicly.

Credentials for your integration (login details or a service account) are provisioned during onboarding via the DGuard Partner Portal.

Step 1: Authenticate

Exchange your credentials for tokens. The most common method is email + password; DGuard also supports social and biometric sign-in.

Request

bash

POST /api/auth/login

Headers

Content-Type: application/json

Body

json

{
  "email": "integration@yourcompany.com",
  "password": "your_password"
}

Success Response (200 OK)

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "usr_123456",
    "email": "integration@yourcompany.com"
  }
}

Other Sign-in Methods

POST /api/auth/social-login

Exchange a verified provider token (Google, Apple) for DGuard tokens.

POST /api/auth/biometric-login

Step 2: Make Authenticated Requests

Include the access token in the Authorization header of every request:

Authorization Header

Authorization: Bearer <access_token>

The JWT access token from Step 1

Example Request

bash

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

Complete Integration Example

javascript

// Step 1: Authenticate to obtain tokens
const authResponse = await fetch("{base_url}/api/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "integration@yourcompany.com",
    password: "your_password"
  })
});
const { access_token, refresh_token } = await authResponse.json();

// Step 2: Call the API with the Bearer token
const apiResponse = await fetch("{base_url}/api/auth/me", {
  headers: {
    "Authorization": `Bearer ${access_token}`,
    "Content-Type": "application/json"
  }
});

Refreshing Tokens

Access tokens are short-lived. When one expires (or is about to), exchange your refresh token for a new access token — no need to re-authenticate with credentials.

bash

POST /api/auth/refresh

Body

json

{
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Success Response (200 OK)

json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

To end a session, call POST /api/auth/logout, which invalidates the refresh token.

Rate Limits

Sandbox

60 requests/minute

1,000 requests/day

Production

1,000 requests/minute

100,000 requests/day

Enterprise

10,000 requests/minute

Unlimited requests/day

Rate Limit Headers

bash

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

Security Recommendations

✓

Store the refresh token securely (secure storage, vault, or env vars)

✓

Never expose tokens in client-side code, logs, or URLs

✓

Use HTTPS exclusively

✓

Cache the access token and refresh it before expiry (expires_in: 3600s)

✓

Implement retry with exponential backoff

✓

Log and monitor all API accesses