Authentication

The v2 API supports two authentication flows. Call your own Vantr account from a trusted server with client credentials, or let other merchants connect their accounts to your app with the OAuth authorization code flow.

Client credentials

Your own account, called from a backend you control. One request, no browser, no user. Covered on this page.

Authorization code + PKCE

A third party connects other merchants’ accounts. Browser redirect plus a per-merchant consent screen. See the guide →

Client secrets are passwords for your integration. Keep them server-side and rotate them if they are ever exposed.

Choose an auth method

Basic auth
Client headers
Bearer token

Use HTTP Basic auth with the client ID as the username and the client secret as the password.

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  "https://api.vantr.ai/v2/products?limit=25"

const credentials = Buffer
  .from(`${process.env.CLIENT_ID}:${process.env.CLIENT_SECRET}`)
  .toString('base64');

const response = await fetch('https://api.vantr.ai/v2/products?limit=25', {
  headers: {
    Authorization: `Basic ${credentials}`,
  },
});

import os
import requests

response = requests.get(
    "https://api.vantr.ai/v2/products",
    params={"limit": 25},
    auth=(os.environ["CLIENT_ID"], os.environ["CLIENT_SECRET"]),
    timeout=20,
)

Use headers when your HTTP client cannot conveniently send Basic auth.

cURL

curl \
  -H "x-client-id: $CLIENT_ID" \
  -H "x-client-secret: $CLIENT_SECRET" \
  "https://api.vantr.ai/v2/products?limit=25"

Exchange the client_credentials grant at /oauth/token for a short-lived access token, then pass it on v2 requests. This keeps your client_secret off individual API calls.

curl -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "scope=products.read categories.read locations.read" \
  "https://api.vantr.ai/oauth/token"

curl -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.vantr.ai/v2/categories/tree"

To act on another merchant’s account instead of your own, use the authorization_code grant — see Authorize a user (OAuth).

Token request

Use application/x-www-form-urlencoded for OAuth token calls.

string

required

Use client_credentials, authorization_code, or refresh_token.

string

Space-separated scopes. Required for client_credentials and authorization_code; optional on refresh when you want to narrow the refreshed access token.

string

Authorization code returned from /oauth/authorize. Required for authorization_code.

string

PKCE verifier that matches the original code_challenge. Required for authorization_code.

string

required

Opaque bearer token to pass in the Authorization header.

integer

required

Lifetime in seconds for the access token.

string

required

Space-separated scopes granted to the token.

string

Returned for the authorization_code grant (unless disabled on the app). Refresh tokens rotate: each refresh revokes the one you used and returns a new one. The client_credentials grant does not issue refresh tokens — just request a new access token. See Authorize a user (OAuth).

Token lifecycle

Issue

Use /oauth/token for client credentials, authorization code, and refresh token grants.

Inspect

Use /oauth/introspect to check token activity and metadata.

Revoke

Use /oauth/revoke to remove access immediately.

Common failures

401 from OAuth token endpoints

Check that the request uses HTTP Basic auth with the client ID and client secret. Also verify that the application secret has not been rotated.

403 from v2 endpoints

The credential is valid, but the application or token does not include a scope accepted by that endpoint. Check the endpoint reference and update the application scope set.

invalid_scope from /oauth/token

Request only scopes that are enabled on the developer application. Use a space-separated scope string, not commas.

FAQ

Which method should I use first?

Start with Basic auth for server-to-server integrations. Move to bearer tokens when your system needs OAuth grant handling or short-lived access tokens.

Can I use client secrets in frontend code?

No. Client secrets must stay in trusted server environments.

Where are scope requirements listed?

Every endpoint in the API reference declares its required scope. The scopes guide lists the full starter set.

Start

Build

Operate

Authentication

Authentication

Client credentials

Authorization code + PKCE

Choose an auth method

Token request

Token lifecycle

Issue

Inspect

Revoke

Common failures

FAQ

​Authentication

Client credentials

Authorization code + PKCE

​Choose an auth method

​Token request

​Token lifecycle

Issue

Inspect

Revoke

​Common failures

​FAQ

Authentication

Choose an auth method

Token request

Token lifecycle

Common failures

FAQ