Authentication

The Dispatch API uses token-based authentication. This guide explains how to authenticate your API requests.

Overview

Authentication Method

Dispatch uses Bearer token authentication:

• Generate an API token from the portal
• Include token in request headers
• Token provides access to your business data

Token Types

Two types of authentication:

1. API Tokens - For server-to-server integrations
2. User Tokens - For user session authentication (portal login)

API Tokens

Generating Tokens

Create an API token:

1. Log into Dispatch Management Portal
2. Navigate to Settings > API Access
3. Click "Generate New Token"
4. Provide a description for the token
5. Copy and securely store the token

Token Display

Important

API tokens are displayed only once at creation. Copy and store securely - you cannot retrieve it later.

Token Format

API tokens are long random strings:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Using Tokens

Authorization Header

Include the token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Example Request

curl -X GET "https://api.dispatch.example.com/api/v1/Orders" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Accept: application/json"

Multiple Languages

JavaScript/Node.js

const response = await fetch('https://api.dispatch.example.com/api/v1/Orders', {
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  }
});

Python

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.dispatch.example.com/api/v1/Orders',
    headers=headers
)

C#

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");

var response = await client.GetAsync(
    "https://api.dispatch.example.com/api/v1/Orders"
);

Token Management

Viewing Tokens

See all active tokens:

1. Go to Settings > API Access
2. View list of tokens
3. See creation date and last used

Token Details

For each token:

• Description/name
• Creation date
• Last used date
• Status (active/revoked)

Revoking Tokens

Revoke tokens that are no longer needed:

1. Go to Settings > API Access
2. Find the token
3. Click "Revoke"
4. Confirm revocation

warning

Revoking a token immediately invalidates it. Any systems using it will stop working.

User Authentication

Login Flow

For user-facing applications:

1. User provides credentials
2. Authenticate via login endpoint
3. Receive session token
4. Use token for subsequent requests

Login Endpoint

POST /api/user/login

Request body:

{
  "email": "[email protected]",
  "password": "userpassword"
}

Registration

New user registration:

POST /api/user/register

Request body:

{
  "email": "[email protected]",
  "password": "password",
  "confirmPassword": "password",
  "firstName": "John",
  "lastName": "Doe",
  "acceptedTerms": true
}

Email Verification

Verify user email:

POST /api/user/verify

Security Best Practices

Token Security

1. Never expose tokens - Don't include in client-side code
2. Use environment variables - Store tokens securely
3. HTTPS only - Always use encrypted connections
4. Limit distribution - Only share with necessary systems

Token Rotation

Regularly rotate tokens:

1. Generate new token
2. Update systems to use new token
3. Verify new token works
4. Revoke old token

Monitoring

Monitor token usage:

• Track API calls per token
• Watch for unusual patterns
• Investigate anomalies
• Set up alerts for suspicious activity

Compromised Tokens

If a token is compromised:

1. Revoke immediately - Stop the token
2. Generate new - Create replacement
3. Update systems - Deploy new token
4. Investigate - Determine how it leaked
5. Audit - Check for unauthorized access

Error Handling

Authentication Errors

Code	Error	Description
401	Unauthorized	Missing or invalid token
403	Forbidden	Valid token but insufficient permissions

Error Response

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

Troubleshooting

401 Unauthorized:

• Check token is included in request
• Verify token format is correct
• Confirm token hasn't been revoked
• Check for typos in header name

403 Forbidden:

• Token valid but lacks permission
• Check user/token access level
• Verify plan includes feature

API Token vs User Token

Aspect	API Token	User Token
Purpose	Server integration	User session
Duration	Long-lived	Session-based
Creation	Manual in portal	Via login
Scope	Full API access	User permissions
Revocation	Manual	Logout/expiry

Rate Limiting

Per-Token Limits

Rate limits apply per token:

• Each token has separate quota
• Limits reset periodically
• Check headers for status

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1234567890

Handling Rate Limits

When rate limited (429 response):

1. Stop making requests
2. Wait for reset time
3. Implement exponential backoff
4. Consider request batching