Credentials & tokens

The token endpoint

POST https://{store domain}/apps/token — the OAuth 2.0 client credentials grant. It is the only grant apps use: an app is installed on one store and presents its own credentials, so there is no user to redirect and no authorization-code flow.

Form field	Value
`grant_type`	exactly `client_credentials`
`client_id`	your `ciqra_ci_…` id
`client_secret`	your `ciqra_cs_…` secret

The body must be application/x-www-form-urlencoded. Credentials in an Authorization: Basic header are not read.

Success — `200`

{
  "accessToken": "ciqra_at_…",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "scope": "read_products write_products",
  "scopeNotYetEnforced": ""
}

Field	Meaning
`accessToken`	Send as `Authorization: Bearer <accessToken>`.
`expiresIn`	Seconds until it expires — one hour by default.
`scope`	Space-separated effective scopes: what was granted, plus the `read_` scope each `write_` scope implies. Order is not significant.
`scopeNotYetEnforced`	The subset of `scope` that no endpoint honours yet (empty string when none). See scopes.

There is no refresh token. Request a new token shortly before expiresIn runs out — the reference app does so one minute early.

Failures

Status	Body	Cause
`400`	`{"error":"invalid_request","errorDescription":"…"}`	Body is not form-encoded.
`400`	`{"error":"unsupported_grant_type","errorDescription":"…"}`	`grant_type` is anything but `client_credentials`.
`401`	(empty)	Unknown client id, wrong secret, app not active, or no active installation on this domain’s store. The cases are deliberately indistinguishable.
`429`	(empty)	More than 20 token requests per minute from your IP address.

The token is bound to one store

The installation is looked up as the store the request’s domain resolves to. The same credentials used on another store’s domain receive 401, even if the app is installed there too — each store’s installation must be addressed on that store’s domain.

Standing tokens

A merchant can issue a long-lived token for an installation from the admin (Settings → Apps → the app → Tokens): a label and a lifetime of 30, 90, 180 or 365 days. It is shown once, carries the installation’s current scopes, and can be revoked individually. The admin shows when each token was last used (updated at most every five minutes).

Use one only for a tool that cannot perform the token exchange. A leaked standing token is valid for months; a leaked exchanged token for under an hour.

Rotation and revocation

Client secret. Rotated by CIQRA on request. The previous secret keeps working for an overlap window (24 hours by default) so you can deploy the new one without downtime.
Revocation is immediate. Tokens are checked against the installation and the app on every request; nothing is cached. Uninstalling the app, revoking a standing token, or suspending the app takes effect on the very next call.
Signing secret. Issued once at installation. There is currently no route to rotate it — see limitations.