Skip to main content

​
Overview

Chidori API keys support granular permissions, allowing you to control exactly what each key can do. This follows the principle of least privilege—only grant the permissions your application actually needs.

​
Available permissions

PermissionDescriptionRequired for
pricing:readGet delivery price estimates/api/pricing/single, /api/pricing/bulk
delivery:createCreate new deliveries/api/deliveries/create, /api/deliveries/create-bulk
delivery:readView delivery details/api/deliveries/get, /api/deliveries/list
payment:createProcess payments/api/payments/charge
payment:readView transaction history/api/payments/list-transactions, /api/payments/get-transaction
webhook:manageManage webhooks/api/webhooks/*
location:readAccess real-time locationWebSocket location updates

​
Permission groups

For convenience, you can think of permissions in logical groups:

​
Pricing permissions

pricing:read
Required to calculate delivery costs before creating deliveries.

​
Delivery permissions

delivery:create
delivery:read
  • delivery:create - Create single or bulk deliveries
  • delivery:read - View and list your deliveries

​
Payment permissions

payment:create
payment:read
  • payment:create - Charge wallet for deliveries
  • payment:read - View transaction history

​
Webhook permissions

webhook:manage
Full control over webhook configuration.

​
Location permissions

location:read
Required for WebSocket real-time tracking.

​
Common permission sets

For development and testing, or when your application needs complete API access:
[
  "pricing:read",
  "delivery:create",
  "delivery:read",
  "payment:create",
  "payment:read",
  "webhook:manage",
  "location:read"
]
For an online store that creates and pays for deliveries:
[
  "pricing:read",
  "delivery:create",
  "delivery:read",
  "payment:create"
]
For a dashboard that only displays delivery status:
[
  "delivery:read",
  "location:read"
]
For a system that generates reports on deliveries and payments:
[
  "delivery:read",
  "payment:read"
]
For a tool that only calculates delivery prices:
[
  "pricing:read"
]

​
Setting permissions

When creating an API key through the dashboard:
1

Navigate to API Keys

Go to chidori.africa/dashboard and open the API Keys section.
2

Create new key

Click Create API Key.
3

Select permissions

Check the boxes for each permission you want to grant. You can select individual permissions or use preset groups.
4

Create the key

Click Create to generate your key with the selected permissions.

​
Permission errors

When you attempt an action without the required permission, you receive a 403 Forbidden response: 
{
  "status": false,
  "message": "Missing required permission: delivery:create"
}

​
Best practices

Least privilege

Only grant permissions that are actually needed. This limits damage if a key is compromised.

Separate keys by function

Create different keys for different parts of your application, each with only the permissions it needs.

Audit regularly

Periodically review your API keys and their permissions. Revoke unused keys.

Document key usage

Keep track of which keys are used where in your infrastructure.

​
Next steps

API Keys

Learn how to create and manage API keys.

API Reference

Explore all available API endpoints.