Authentication

Carriyo API supports OAuth2.0 authentication. To access any Carriyo API you must first get an Oauth Access Token.

Get Access Token

This authentication endpoint takes the client_id and client_secret and returns an access token.

The access token returned by this endpoint should be used as a bearer token in the 'Authorization' header for any subsequent Carriyo API endpoints.

The access token should be cached on the client side until its expiry.

Request Body schema: application/json
required

OAuth Request (to get access token)

client_id
required
string

The client ID generated in the Carriyo Dashboard

client_secret
required
string

The client secret generated in the Carriyo Dashboard

application/json
{
  • "client_id": "<YOUR-CLIENT-ID>",
  • "client_secret": "<YOUR-CLIENT-SECRET>"
}

Success Response

Response Schema: application/json
access_token
required
string

The OAuth access token to be used for API calls

scope
required
string

The permissions granted to the oauth token

expires_in
required
number

Expiry time in milli seconds

token_type
required
string

Token type - Bearer

application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL",
  • "scope": "tenant:TEST merchant:ACCOUNT read:shipments create:shipments update:shipments",
  • "expires_in": 86400,
  • "token_type": "Bearer"
}

Error Response

Response Schema: application/json
error
required
string

The type of error

error_description
required
string

The error description

application/json
{
  • "error": "access_denied",
  • "error_description": "Unauthorized"
}
Loading...

Make your first call

Once you have the access token, you must pass the following headers to make an API call:

  • tenant-id: YOUR-TENANT-ID
  • x-api-key: YOUR-API-KEY
  • Authorization: Bearer YOUR-OAUTH-ACCESS-TOKEN

Follow these steps to make your first call to the Carriyo API

Step 1. Copy your Tenant ID and API Key from the Carriyo Dashboard

Login as a Carriyo admin to perform this action Copy Tenant ID and API Key

Step 2. Create a new Client Application to get your Client ID and Client Secret

Login as a Carriyo admin to perform this action Copy the Client ID and Client Secret

Step 3. Request for the Oauth Access Token using the Client ID and Client Secret

Use the cURL command below

Copy
Copied
curl --location --request POST 'https://api.carriyo.com/oauth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_id": "YOUR-CLIENT-ID",
    "client_secret": "YOUR-CLIENT-SECRET"
}'
Authentication Steps Complete

You now have the credentials to make your first API call

Step 4. Now call the Carriyo endpoint with the Tenant ID, API Key and Access Token

Let's try to create your first shipment.

Click here to see use the 'Try It' console to create your draft shipment

Or you can use the 'cURL' command below

Copy
Copied
curl --location --request POST 'https://api.carriyo.com/shipments?draft=true' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR-API-KEY' \
--header 'tenant-id: YOUR-TENANT-ID' \
--header 'Authorization: Bearer YOUR-OAUTH-ACCESS-TOKEN' \
--data-raw '{
    "references": {
        "partner_order_reference": "my_first_shipment_1",
        "partner_shipment_reference": "my_first_shipment_1"
    },
    "payment": {
        "payment_mode": "PRE_PAID",
        "total_amount": 100.0,
        "currency": "USD"
    },
    "items": [
        {
            "description": "CARRIYO T-SHIRT",
            "quantity": 1,
            "price": {
                "amount": 100.0,
                "currency": "USD"
            },
            "sku": "S12345"
        }
    ],
    "dropoff": {
        "contact_name": "My Customer",
        "contact_phone": "+971561111234",
        "contact_email": "mycustomer@gmail.com",
        "address1": "101 Dubai Maina Promenade",
        "city": "DUBAI",
        "country": "AE",
        "coords": [
            24.2495705,
            55.6900005
        ]
    }
}'