Authenticate with API keys and OAuth

Every request to the OLET public API needs either an API key or an OAuth access token in the Authorization header. Use an API key for a script or an internal integration you control; use OAuth when you are building something a merchant installs and approves themselves.

How do I authenticate a request

Send the credential as a bearer token:

curl https://api.oletapp.com/your-store/v1/me \
  -H "Authorization: Bearer olet_live_YOUR_API_KEY"

const response = await fetch('https://api.oletapp.com/your-store/v1/me', {
  headers: { Authorization: 'Bearer olet_live_YOUR_API_KEY' },
})

An OAuth access token goes in the same header, in place of the API key.

Where do I create an API key

In the back office, go to Integrations, then API & apps, and click Create API key under API keys. Give the key a name and tick the scopes it needs, grouped as Catalog, Inventory, Customers and Sales. Only the Catalog read scope is ticked to start with, and ticking a write scope also ticks its read scope. Click Create key, then copy the key from the API key created window. It reads “Copy this key now. You won’t be able to see it again.”

Only store admins can open this page, and creating a key needs the Growth plan. Your API base URL is shown above the key list, ready to copy.

To stop a key, click the revoke button on its row and confirm with Revoke key. Apps using it stop working immediately.

What does OAuth look like

OLET supports the standard authorization code flow, with PKCE (S256) supported for public clients.

1. Send the merchant to authorize:

   https://admin.oletapp.com/oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=catalog:read+sales:read&state=YOUR_STATE

   Only response_type=code is supported. To use PKCE, also send code_challenge and code_challenge_method=S256.

2. The merchant signs in and sees Connect YOUR_APP to YOUR_STORE, with the access your app asked for. They click Allow access or Cancel. OLET then redirects back to your redirect_uri with a code (or error=access_denied on Cancel), and your state echoed back.

3. Exchange the code within 10 minutes. A code works once.

   curl https://api.oletapp.com/oauth/token \
     -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
     -d grant_type=authorization_code \
     -d code=THE_CODE \
     -d redirect_uri=YOUR_REDIRECT_URI

   Send the client credentials either as HTTP Basic auth, as above, or as client_id and client_secret in the body, but not both. If you used PKCE, add code_verifier.

The response carries access_token, refresh_token, token_type (Bearer), expires_in (3600), scope (the granted scopes, separated by spaces), store_name, and api_base_url, the exact base URL to call for this store.

An access token lasts 1 hour. When it expires, exchange the refresh token for a new access token with grant_type=refresh_token and refresh_token=THE_REFRESH_TOKEN. The refresh token itself does not rotate: you get the same refresh token back every time, so keep using it.

POST /oauth/token errors use the OAuth shape, {"error": "invalid_grant", "error_description": "..."}, not the usual error envelope. A code or token that is wrong, expired or already used answers invalid_grant. Bad client credentials answer 401 invalid_client.

To register an OAuth app, email support@getolet.com. Client creation is not yet self-serve.

What does the merchant see

Connected apps appear under Connected apps on the same API & apps page, with the app name, its access, who approved it, and when it was last used. The merchant can click the disconnect button and confirm with Disconnect to cut the connection. Automations using it stop right away, and the app can ask again.

If the signed-in user is not an admin, the consent screen reads “Only store admins can connect apps” and asks them to get an admin to connect your app. If the store is not on the Growth plan, it reads “Connecting apps needs the Growth plan.” and offers See plans.

What can a credential do

Both API keys and OAuth connections carry a set of scopes that limit what they can read or write.

Scope	Grants
catalog:read	View products, prices, categories, brands, tags and suppliers
catalog:write	Create, update and delete products, brands, categories, tags and suppliers
inventory:read	View stock levels across outlets
inventory:write	Adjust stock levels across outlets
customers:read	View customers, including names, emails and phone numbers
customers:write	Create and update customers, and permanently erase a customer’s personal details. Erasure cannot be undone.
sales:read	View completed sales and refunds

A :write scope also satisfies the matching :read requirement, so a key with catalog:write can call a catalog:read endpoint too. There is no sales:write scope, because the API only reads sales.

A few reference endpoints need no particular scope, so any valid credential can call them: GET /me, GET /store, GET /outlets, GET /payment-types and GET /taxes. They explain the ids and prices that the scoped endpoints return.

A call without the right scope answers 403 INSUFFICIENT_SCOPE.

What happens if a credential goes idle

An API key or an OAuth connection that goes 90 days without a request stops working. A key that was never used counts from the day it was created. There is no separate warning; the next request answers UNAUTHORIZED. The back office shows it as Expired. Create a new key or reconnect to keep going.

Finding your store prefix

Every path starts with your store’s prefix, for example your-store in https://api.oletapp.com/your-store/v1/products. You can find it two ways: call GET /me with any valid credential, or read api_base_url from an OAuth token response.

Where to go next

See the error codes you might get back, or browse the full API reference.