Authentication

For a short step-by-step walkthrough, see the Make your first API call tutorial.

Overview

The Quivo API uses OAuth 2.0 with the client credentials grant. Your integration authenticates with an API credential: a client ID and a client secret that belong to one seller. An Account Admin creates it in The Connector web app. You exchange the credential for an access token and send that token on every API call. Switching from POST /login? See Migrate to OAuth 2.0 API credentials. The flow has two steps:

Get an access token: Send your client ID and client secret to POST ${BASE_URL}/v2/oauth2/token.
Call the API: Send the access token in the Authorization: Bearer header on every call to ${BASE_URL}/v2/....

You do not need an X-Api-Key header.

Prerequisites

Before you start, make sure you have:

Client ID: The ID of your API credential. It starts with qak_.
Client secret: The secret of the same credential. The Connector shows it only once, when you create or rotate the credential.

To create a credential, see Create an API credential.

All API examples in this guide use ${BASE_URL} as a placeholder. Replace it with the correct base URL configured for the correct environment. For more information see Environments page.

The Python and Node.js examples read the base URL from the BASE_URL environment variable. Set it before you run them, for example export BASE_URL="https://api-sandbox.quivo.co".

Obtain an access token

Send a POST request to ${BASE_URL}/v2/oauth2/token with the body grant_type=client_credentials. Use the content type application/x-www-form-urlencoded. Authenticate with HTTP Basic: the client ID is the username and the client secret is the password.

curl
Python
Node.js
Response

curl -X POST "${BASE_URL}/v2/oauth2/token" \
  -u "your-credential-id:your-secret" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials"

import os
import requests

BASE_URL = os.environ["BASE_URL"]

response = requests.post(
    f"{BASE_URL}/v2/oauth2/token",
    data={"grant_type": "client_credentials"},
    auth=("your-credential-id", "your-secret"),
    timeout=10,
)
response.raise_for_status()
access_token = response.json()["access_token"]

const BASE_URL = process.env.BASE_URL;
const basic = Buffer.from("your-credential-id:your-secret").toString("base64");

const response = await fetch(`${BASE_URL}/v2/oauth2/token`, {
  method: "POST",
  headers: {
    Authorization: `Basic ${basic}`,
    "Content-Type": "application/x-www-form-urlencoded",
  },
  body: new URLSearchParams({ grant_type: "client_credentials" }),
});
if (!response.ok) {
  throw new Error(`Token request failed: ${response.status}`);
}
const { access_token } = await response.json();

A successful request returns 200 OK:

{
  "access_token": "<YOUR_ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "api"
}

The Node.js example needs Node.js 18 or later for the built-in fetch. It uses top-level await, so run it as an ES module (for example, a .mjs file).

The examples show placeholder values. In your integration, load the client ID and client secret from environment variables or a secrets manager. Never commit a real client secret to a code repository.

If your HTTP client cannot send Basic authentication, send the credential as form fields instead: grant_type=client_credentials&client_id=your-credential-id&client_secret=your-secret. The scope parameter is optional. If you send it, its value must be api. Any other value returns 400 with {"error": "invalid_scope"}.

Use the token

Send the access token in the Authorization header as a Bearer token. With an access token, all API paths start with /v2. The paths after /v2 are the same as in the API reference. The following example lists your orders.

Request
Response

curl -X GET "${BASE_URL}/v2/orders" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

A successful request returns 200 OK with your orders.If the token is missing, unknown or expired, the API returns 401 Unauthorized with the header WWW-Authenticate: Bearer:

{
  "message": "Unauthorized"
}

Token expiration

An access token is valid for 3600 seconds (one hour). The expires_in field in the token response tells you how long it is valid. There is no refresh token. To continue, request a new access token with your client ID and client secret.

Reuse one access token for all calls until it expires. Request a new token shortly before it expires, or when a call returns 401 Unauthorized. Then retry the call that failed.

Errors

The token endpoint returns errors as a JSON body with an error field, for example {"error": "invalid_client"}.

Status	`error`	Meaning
`400`	`invalid_request`	The request is malformed. For example, a parameter is missing or the body is not form-encoded.
`400`	`unsupported_grant_type`	`grant_type` is not `client_credentials`.
`400`	`invalid_scope`	`scope` has a value other than `api`.
`401`	`invalid_client`	The client ID is unknown, the client secret is wrong, or the credential is revoked or expired. The answer is the same in every case.
`503`	`server_error`	The token service is unavailable. Retry with backoff.

How to react to an error:

API call returns 401 Unauthorized: The access token is missing, unknown or expired. Request a new access token and retry the call once.
Token request returns 401 with invalid_client: A new attempt with the same client ID and client secret will not succeed. Stop retrying. Check the client ID and client secret, and check the credential in The Connector. If it is revoked or expired, create or rotate a credential and update your integration.
Token request returns 503 with server_error: Retry with exponential backoff and a limit on the number of attempts.
400 errors: Fix the request. Retrying the same request returns the same error.

Rate limits

Rate limits apply per API credential. The default limit is 2 requests per second, with a burst of up to 40 requests. If you send more requests than the limit allows, the API returns 429 Too Many Requests with the header Retry-After: 1. Wait at least the number of seconds in Retry-After, then retry. If you have agreed a higher limit with Quivo, new and rotated credentials get it automatically. If you need a higher limit, contact Quivo. POST /login with a Connector username, password and the X-Api-Key header is deprecated. Existing integrations keep working until 31 January 2027. From 1 February 2027, the API accepts integrations only with an API credential. To switch, see Migrate to OAuth 2.0 API credentials. The old method is documented in Legacy login (deprecated).

Where to go next

Now that you understand authentication, continue with these guides:

Create a Fulfillment Order

Start the fulfillment process by creating orders for your customers.

Send Inventory

Send your products to Quivo warehouses to make them available for fulfillment.

Introduction

Endpoints

Overview

Prerequisites

Obtain an access token

Use the token

Token expiration

Errors

Rate limits

Where to go next

Create a Fulfillment Order

Send Inventory

​Overview

​Prerequisites

​Obtain an access token

​Use the token

​Token expiration

​Errors

​Rate limits

​Legacy login

​Where to go next

Create a Fulfillment Order

Send Inventory

Overview

Prerequisites

Obtain an access token

Use the token

Token expiration

Errors

Rate limits

Legacy login

Where to go next