Skip to main content

API Authentication

Learn how to authenticate with the DZDESK API.

Overview​

The DZDESK API uses secure authentication to protect your data. Two authentication methods are supported:

  • API Keys: For server-to-server integrations
  • OAuth 2.0: For user-context operations

API Keys​

Creating an API Key​

  1. Navigate to Settings > API
  2. Click Generate API Key
  3. Enter:
    • Key name (for identification)
    • Permissions scope
    • Expiration (optional)
  4. Click Create
  5. Copy the key immediately (shown only once)

Using API Keys​

Include the API key in request headers:

curl -X GET "https://api.dzdesk.com/v1/requests" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Key Permissions​

ScopeAccess
requests:readRead requests
requests:writeCreate/update requests
users:readRead user data
users:writeManage users
adminFull access

Key Best Practices​

  1. Minimum permissions: Only grant needed scopes
  2. Rotate regularly: Change keys periodically
  3. Secure storage: Never commit keys to code
  4. Monitor usage: Review API logs

OAuth 2.0​

When to Use OAuth​

Use OAuth when:

  • Acting on behalf of a user
  • Building user-facing integrations
  • Need user-level permissions

OAuth Flow​

1. Redirect user to authorization URL
2. User approves access
3. Receive authorization code
4. Exchange code for access token
5. Use token for API requests

Authorization URL​

https://api.dzdesk.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=requests:read requests:write

Token Exchange​

curl -X POST "https://api.dzdesk.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

Token Response​

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2..."
}

Refreshing Tokens​

curl -X POST "https://api.dzdesk.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

API Base URL​

All API requests use:

https://api.dzdesk.com/v1/

Request Headers​

Required headers for all requests:

HeaderValue
AuthorizationBearer YOUR_TOKEN
Content-Typeapplication/json
Acceptapplication/json

Response Format​

Success Response​

{
  "success": true,
  "data": {
    // Response data
  }
}

Error Response​

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

Error Codes​

CodeHTTP StatusDescription
UNAUTHORIZED401Invalid or missing token
FORBIDDEN403Insufficient permissions
NOT_FOUND404Resource not found
RATE_LIMITED429Too many requests
SERVER_ERROR500Internal server error

Rate Limits​

API requests are rate limited:

PlanLimit
Standard60 requests/minute
Professional300 requests/minute
EnterpriseCustom

Rate Limit Headers​

Responses include:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1642694400

Handling Rate Limits​

When rate limited (HTTP 429):

  1. Wait until reset time
  2. Implement exponential backoff
  3. Consider caching responses

Security Requirements​

HTTPS Only​

All API requests must use HTTPS.

Token Security​

  • Never share tokens
  • Don't log tokens
  • Use environment variables
  • Rotate compromised tokens

IP Allowlisting (Optional)​

Restrict API access by IP:

  1. Go to Settings > API
  2. Add allowed IP addresses
  3. Only listed IPs can access

Testing Authentication​

Verify Token​

curl -X GET "https://api.dzdesk.com/v1/me" \
  -H "Authorization: Bearer YOUR_TOKEN"

Expected Response​

{
  "success": true,
  "data": {
    "id": "user_123",
    "email": "user@company.com",
    "role": "agent",
    "scopes": ["requests:read", "requests:write"]
  }
}