Authentication
How your app proves who it is when calling the Otter API — and how you verify that inbound webhooks really came from Otter.
There are two directions:
| Direction | What you do | Primary mechanism |
|---|---|---|
| Outbound — your app → Otter | Call REST endpoints | OAuth 2.0 access token as Authorization: Bearer … |
| Inbound — Otter → your app | Receive webhooks | Validate X-HMAC-SHA256 on every request |
Exact token request/response fields live in the API reference. Code samples for webhook HMAC live in Keep webhooks secure.
Application credentials
Your Account Representative registers an application and gives you:
- Client ID (Application ID / Partner ID in older materials — same value)
- Client secret
Never commit secrets to source control or expose them in a browser or mobile app.
See Quickstart to obtain credentials and complete a first call.
Calling the Otter API (outbound)
Access tokens
Request an access token from POST /v1/auth/token using your Client ID and client secret.
Two common OAuth 2.0 flows:
| Flow | When to use |
|---|---|
| Client credentials | Server-to-server integration — no end-user login. Most partner integrations start here. |
| Authorization code | A merchant user must authorize your app (for example organization onboarding). Starts at GET /v1/auth/oauth2/authorize, then exchange the code at /v1/auth/token. |
Example shape (client credentials — fill hosts and values from the API reference):
curl --request POST 'https://{{otter-api-url}}/v1/auth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'scope=ping' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=[CLIENT_ID]' \
--data-urlencode 'client_secret=[CLIENT_SECRET]'
The response includes access_token, token_type (bearer), and expiry (expired_in / related fields — see API reference). Tokens are typically valid for a fixed window (currently on the order of 30 minutes); refresh by requesting a new token before expiry.
Request headers
On resource calls:
Authorization: Bearer <access_token>
X-Store-Id: <store_id>
Authorization— required on resource endpoints.X-Store-Id— required on store-scoped endpoints. Identifies which linked store the call acts on. See Stores and connections and Quickstart — connect stores.
Scopes
Tokens and applications are limited by scopes (for example organization or orders scopes). Request only what you need. Missing scope → authorization errors even with a valid token. Scope lists are in the API reference.
Transient 401s
Occasionally a valid token can return 401 during internal auth edge cases. Prefer a short retry with backoff for known-good tokens, or request a new token — see the auth notes in the API reference.
Verifying webhooks (inbound)
Otter sends HTTPS POST events to URLs you register. Each endpoint has a secret and an optional Authorization style (Basic, Bearer, legacy HMAC SHA1, or none).
Always validate the X-HMAC-SHA256 header (HMAC-SHA256 of the raw body with your webhook secret) before trusting the payload — regardless of Authorization type.
Do not process webhook bodies without signature validation.
Deep guide with algorithms and multi-language samples: Keep webhooks secure. Event model (ack, retries, error callbacks): Events and webhooks.
Related
- Quickstart — first token, store header, webhook registration
- Events and webhooks — REST vs webhooks, ack, error callbacks
- Stores and connections — pairing and
X-Store-Id - Keep webhooks secure — HMAC how-to and samples
- Understand rate limits
- Otter 101
- API reference — auth
Next
Wire client-credentials tokens, then complete Events and webhooks and Keep webhooks secure before live traffic.