Enable the API
Using the API takes two switches and one key. The first switch is on the platform side, the second is in your company settings, and the key is created in the dashboard by a company admin.
The platform (GROperator) decides which companies may use the API. The channel is called API integration. If it has not been granted to your company, the dashboard page for API access tells you so and asks you to contact the platform, and every API call answers 403 channel_disabled.
A company admin opens Settings, Company and finds the section Shipment creation channels and integration (in the Arabic dashboard: قنوات إنشاء الشحنات والربط). Turn on API integration (الربط البرمجي). While the channel is off, existing keys stop working too, and no new key can be created.
- Open Settings, API access (الربط البرمجي).
- Create a key and give it a name that says what uses it, for example
WebsiteorGoogle Sheets. - Choose its scopes (see the table below). Give the key only what the integration needs. A key can never carry more than the admin who creates it: if you request a scope whose underlying dashboard permissions you do not personally hold, the creation is refused.
- Optionally set an expiry date.
- Save. The dashboard shows the key (it starts with
lmc_live_) and the secret.
The secret is shown once. Copy it into your server's secret store right away. If you lose it, revoke the key and create a new one: the platform stores only a one-way hash of the secret and cannot show it again.
Revoked and expired keys answer 401 unauthorized. A company can hold at most 20 active keys, so revoke the ones you no longer use. A revoked key can then be deleted.
A scope is a permission attached to a key. A scope that only writes does not include reading: an integration that creates shipments and then reads them back needs both shipments:write and shipments:read.
| Scope | What it allows | Endpoints |
|---|---|---|
shipments:readRead shipments | List shipments and read their details, tracking timeline, label and the status catalogue. |
|
shipments:writeWrite shipments | Create, update and cancel shipments. Does not include reading: add shipments:read too. |
|
merchants:readRead merchants | List merchants and read their details and saved addresses. |
|
merchants:writeWrite merchants | Create and update merchants and manage their saved addresses. Does not include reading. |
|
geography:readRead geography | Countries, cities, districts, address validation (resolve) and coverage. |
|
pricing:readRead pricing | Quote the price of a shipment. |
|
branches:readRead branches | List the branches of the company and read one branch. |
|
webhooks:manageManage webhooks | Create, list, test, rotate and delete webhook subscriptions, and read the event catalogue. |
|
Calling an endpoint without its scope answers 403 forbidden with details.requiredScope naming the missing one. GET /auth/me and the two sign-in endpoints need no scope.
curl "https://api.goldrock.live/api/public/v1/auth/me" \
-H "X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "X-API-Secret: YOUR_API_SECRET"const response = await fetch("https://api.goldrock.live/api/public/v1/auth/me", {
method: "GET",
headers: {
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET"
},
});
const data = await response.json();
console.log(response.status, data);<?php
$url = 'https://api.goldrock.live/api/public/v1/auth/me';
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
'X-API-Secret: YOUR_API_SECRET',
],
]);
$result = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
var_dump($status, json_decode($result, true));import requests
response = requests.request(
"GET",
"https://api.goldrock.live/api/public/v1/auth/me",
headers={
"X-API-Key": "lmc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"X-API-Secret": "YOUR_API_SECRET",
},
timeout=30,
)
print(response.status_code, response.json())A 200 answer confirms the credentials, the scopes and the channel. Then continue with Authentication for the security rules, or go straight to the quickstart.
If you prefer to act as a user (or give merchants a login), no key is needed: the user signs in with POST /auth/login. The API channel must still be on for the company. See Authentication.