API Key Authentication

All API requests to Deliverty Hub require authentication via an API key. The key is provided in the x-api-key HTTP header with every request.

The API key is generated when an organization administrator creates a channel. Each key is tied to a specific user account and organization, which means:

• All tasks created through the API are automatically scoped to the channel's organization.
• The API key inherits the permissions of the associated user account.
• Audit logs record all actions against the associated user.

Making Authenticated Requests

Include the x-api-key header in every HTTP request:

Example Requests

cURL

curl -X GET https://api.deliverty.com/api/v1/tasks \
  -H "x-api-key: dh_live_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json"

Creating a Task

curl -X POST https://api.deliverty.com/api/v1/tasks \
  -H "x-api-key: dh_live_a1b2c3d4e5f6g7h8i9j0" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DELIVERY",
    "customer": {
      "name": "John Doe",
      "phone": "+1234567890"
    },
    "pickupLocation": {
      "address": "123 Warehouse St",
      "latitude": 33.8938,
      "longitude": 35.5018
    },
    "dropoffLocation": {
      "address": "456 Customer Ave",
      "latitude": 33.8886,
      "longitude": 35.4955
    }
  }'

JavaScript (fetch)

const response = await fetch('https://api.deliverty.com/api/v1/tasks', {
  method: 'GET',
  headers: {
    'x-api-key': 'dh_live_a1b2c3d4e5f6g7h8i9j0',
    'Content-Type': 'application/json',
  },
});

const tasks = await response.json();

Authentication Errors

If authentication fails, the API returns one of the following error responses:

Status Code	Error	Description
401	Unauthorized	The x-api-key header is missing or the API key is invalid.
403	Forbidden	The API key is valid but the channel is INACTIVE or SUSPENDED.
403	Forbidden	The authenticated user does not have permission to perform the requested action.

Example error response:

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

Security Best Practices

• Use environment variables — Store the API key in an environment variable or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault). Never hardcode it in source files.
• HTTPS only — All API requests must use HTTPS. HTTP requests will be rejected.
• Rotate keys regularly — Regenerate your API key periodically. After regeneration, the old key is immediately invalidated.
• Monitor usage — Review your channel's API activity in the dashboard to detect any unusual patterns.
• Limit permissions — Ensure the user account associated with the channel has only the permissions it needs (principle of least privilege).

Key Regeneration

If an API key is compromised or needs rotation, an organization admin can regenerate it from the dashboard:

1. Navigate to Channels in the dashboard.
2. Select the channel.
3. Click Regenerate API Key.
4. Copy the new key immediately — it will only be shown once.
5. Update the key in all systems that use this channel.