Authentication

The Inventory API uses the OAuth 2.0 client-credentials flow (machine-to-machine): you exchange a client ID and secret for a short-lived access token, then send that token — plus a namespace header — on every request.

What you’ll receive

Provided at onboarding, one set per environment. The client secret is delivered separately through a secure channel — treat it like a password.

Value	Description	Example
Client ID	Identifies your service account	`your-user@your-org`
Client Secret	Your credential (delivered securely)	`xxxxxxxxxxxxxxxxxxxxxxxxxxxx`
Project ID	The project your inventory belongs to	`01ABCDEFGHIJKLMNOPQRSTUVWX`

Step 1 — Get an access token

POST to the token endpoint with an application/x-www-form-urlencoded body. All values must be URL-encoded (the @ in a client ID becomes %40).

POST /oauth/v2/token HTTP/1.1
Host: auth.dev.retailmedia.verve.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=client_credentials&client_id=your-user%40your-org&client_secret=your-client-secret&scope=openid

Parameter	Value
`grant_type`	`client_credentials`
`client_id`	(your client ID)
`client_secret`	(your client secret)
`scope`	`openid`

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 43199,
  "scope": "openid"
}

Step 2 — Call the API

Every authenticated request needs two headers:

Header	Value
`Authorization`	`Bearer <access_token>`
`X-Verve-Namespace`	`project:<PROJECT_ID>`

POST /v1alpha/inventory/devices HTTP/1.1
Host: api.dev.retailmedia.verve.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6...
X-Verve-Namespace: project:01ABCDEFGHIJKLMNOPQRSTUVWX
Content-Type: application/json

{}

A 200 response (even with an empty body) means authentication and authorization are working.

Token lifetime

Tokens are short-lived — check expires_in (seconds) on the response.
There is no refresh token in this flow; just repeat Step 1 when the token nears expiry.