Authentication

Every EcomSolo API request authenticates with a single API key, sent as a bearer token. This page covers the key format, scopes, the plan requirement, and how to keep keys safe.

Key format and the bearer header

An API key secret starts with esk_live_ followed by 32 characters. Send it in the Authorization header on every request:

Authorization: Bearer esk_live_...

A missing, malformed, unknown, or revoked key returns 401 Unauthorized.

Creating a key

API keys are created in the EcomSolo platform under Settings → API keys.

• Only the account owner can create keys.
• The account must be on the Advanced plan or above for keys to work against the data endpoints.
• The full secret is shown once, at creation. Copy it immediately — only a short prefix is stored on our side, so it can never be shown again. If you lose it, revoke the key and create a new one.

Scopes

Assign scopes when you create a key:

• read_data — required for every endpoint available today: account, stores, datasets, and query. If a key lacks this scope, data endpoints return 403 with an "Insufficient scope" message.
• exports — reserved for a future export API. It grants nothing today; you can assign it now so keys are ready when that API ships.

The plan requirement

The data endpoints require the Advanced plan or above. If your account's plan does not include the API, those endpoints return 403 with a "Plan upgrade required" message.

The one exception is GET /v1/account: it is not plan-gated and always answers, reporting api_enabled: false when the plan does not include the API. Use it to diagnose whether a 403 is a plan problem or a scope problem.

Revoking a key

You can revoke a key at any time from Settings → API keys. Revocation takes effect immediately — the next request with that key returns 401. Because you can revoke keys individually, use one key per integration so retiring one never disrupts the others.

When access ends

Beyond revoking a key yourself, API access ends automatically when the relationship it depends on ends. This is deliberate: EcomSolo may not keep serving a store's data after you stop connecting that store to us.

What happens	Effect on your keys	How fast
You revoke a key	That key returns 401	Immediately
You uninstall one store, and others remain	Keys keep working, but that store's data disappears from /v1/query and /v1/stores. A key restricted to only that store is revoked.	On the next request
You uninstall your last store	All keys for the account are revoked	On the next request
Your subscription lapses or is cancelled	Data endpoints return 403	On the next request
You downgrade below Advanced	Data endpoints return 403	On the next request

There is no cache in front of any of these checks — your key and your plan are verified on every single request, so the worst case is the next call, not a timeout you have to wait out.

Two consequences worth planning for:

• A revoked key never comes back. If you reinstall a store, previously issued keys stay dead. Create a new key and update your integration.
• GET /v1/account keeps answering even when the data endpoints are refusing, so your integration can tell why it lost access. Check api_enabled — false means the plan or subscription is the problem, while a 401 means the key itself is gone.

Security best practices

• Use keys server-side only. Never embed a key in browser JavaScript, a mobile app, or any client anyone else can inspect.
• Store the secret in an environment variable or a secrets manager, not in source control.
• Use a separate key per integration so you can revoke one without affecting the rest.
• Rotate keys periodically: create the replacement, cut over, then revoke the old one.
• Read Acceptable use before you build. A key acts with your authority, and a few rules travel with the data — including a prohibition on using it to train AI or machine-learning models.