Requests use the HTTP Authorization header to both authenticate and authorize operations. The Convoy API accepts bearer tokens in this header. Bearer tokens are short-lived (24 hour expiration) and can be retrieved from our authentication endpoint and then sent as part of the request. You should receive a <CLIENT_ID> and <CLIENT_SECRET> from Convoy to make these requests.
Retrieving a <BEARER_TOKEN> in production:
{
"method": "post",
"url": "/oauth/token",
"baseUrl": "https://accounts.convoy.com",
"headers": {
"Content-Type": "application/json"
},
"body": {
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
"audience": "https://developer.convoy.com",
"grant_type": "client_credentials",
"scope": "create:loads"
}
}Retrieving a <BEARER_TOKEN> in demo:
{
"method": "post",
"url": "/oauth/token",
"baseUrl": "https://demo-accounts.convoy.com",
"headers": {
"Content-Type": "application/json"
},
"body": {
"client_id": "<CLIENT_ID>",
"client_secret": "<CLIENT_SECRET>",
"audience": "https://demo-developer.convoy.com",
"grant_type": "client_credentials",
"scope": "create:loads"
}
}Making a request in production:
{
"method": "get",
"url": "https://developer.convoy.com/operation-name",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer <BEARER_TOKEN>",
"X-Convoy-Api-Version": "2025-09-01"
}
}Making a request in demo:
{
"method": "get",
"url": "https://demo-developer.convoy.com/operation-name",
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer <BEARER_TOKEN>",
"X-Convoy-Api-Version": "2025-09-01"
}
}