Get Your API Key
Log in to the Subotiz merchant dashboard and navigate to Settings > Developer Settings to view and manage your API Keys.
Note: Your API Key is shown in full only once at creation time. Store it securely. If lost, you will need to generate a new one — the old key will be immediately invalidated.
Making Authenticated Requests
Request Header Format
All OpenAPI requests must include the following HTTP header:
| Header | Value | Description |
|---|---|---|
Authorization | Bearer {your_api_key} | Replace {your_api_key} with your actual API Key |
Example
curl -X GET "https://api.subotiz.com/openapi/v1/orders" \
-H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx"Key Rotation
When a key is compromised or needs periodic renewal, you can rotate it from the Developer Settings page.
Rotation Process
- Initiate key rotation in Developer Settings — a new API Key will be generated
- The system sets a grace period for the old key (default: 3 minutes, customizable at rotation time)
- During the grace period, both old and new keys are valid — update your services to use the new key as soon as possible
- After the grace period ends, the old key is automatically invalidated; only the new key remains valid
Note: Complete the switch to the new key before the grace period ends to avoid request interruptions. If you have Webhooks configured, key rotation also affects Webhook signature verification — it is recommended to support both old and new keys for signature validation during the grace period. See Webhook Introduction for details.
Error Handling
When authentication fails, the API returns an HTTP 401 status code. The following table lists common error causes and recommended actions:
| Error Cause | What to Do |
|---|---|
Missing Authorization header | Ensure your request includes Authorization: Bearer {key} |
| Invalid or non-existent API Key | Verify the key is correct, or retrieve it again from the dashboard |
| API Key expired or revoked | Generate a new key from Developer Settings |
Malformed Authorization header | Ensure the format is Bearer {key} with exactly one space after Bearer |
Error response example:
{
"code": "unauthorizedError",
"message": "ApiKey authentication is required"
}