Authentication
Every metered Stylor endpoint is authenticated with an organization API key. Keys belong to an organization, not a person. Requests made with a key act on that organization's datasets and draw on its plan.
Key types
Each key pair you create has two halves with different jobs.
| Public key | Private key | |
|---|---|---|
| Format | sgpt-pk-… |
sgpt-sk-…::… |
| Safe in browser or mobile code | Yes | No, server-side only |
| Reaches | Shopper-facing endpoints: search, chat messages, available genders, widget preflight | Management endpoints: datasets, items, queue, data sources, sync, chat history, image upload |
| Shown in the dashboard | Always | Once, when the key is created |
A public key can only read your catalogue and talk to the stylist, so exposing it in a web page is expected. A private key can create, change and delete catalogue data. Treat it like a password: keep it in a secret manager or environment variable, never commit it, and never ship it to a client.
Sending the key
Send the key in the Authorization header as a Bearer token:
Authorization: Bearer $STYLOR_API_KEYcurl https://stylor.ai/api/v1/datasets \
-H "Authorization: Bearer $STYLOR_API_KEY"Send the whole key exactly as the dashboard shows it. For a private key that includes the :: and everything after it.
Which key each endpoint needs
Each endpoint accepts exactly one key type. Sending the other type fails with 401, even when both keys come from the same pair.
| Endpoint group | Key |
|---|---|
| Datasets: list, create, retrieve, update, delete, activate, archive, detect | Private |
| Datasets: available genders | Public |
| Dataset items and ingest queue | Private |
| Data sources | Private |
| Sync jobs and sync logs | Private |
| Search | Public |
| Chat: send a message | Public |
| Chat: create, list, retrieve, replace messages, delete | Private |
| Widget preflight | Public |
Image upload (POST /v1/file/upload) |
Private |
Image upload (POST /v1/file/upload/session) |
Private, or a signed-in session |
Image delivery (GET /v1/image/{key}) |
None |
Events (POST /v1/events) |
None. Uses the session token from widget preflight in the X-Stylor-Session header. |
Each endpoint's reference page also lists its key type.
Getting keys
- Sign in to the Stylor dashboard and select your organization.
- Open the API Keys page from the sidebar.
- Choose Create Key and give the key a name.
- Copy both keys straight away. The private key is shown only in this dialog and cannot be viewed again once you close it.
Creating and deleting keys depends on your role in the organization. If you don't see the option, ask an owner or admin. An organization can hold several key pairs at once, which makes rotation possible without downtime.
A key only works while its organization has an active subscription. Without one, requests fail with 403 even if the key itself is valid.
Restricting where a key works
Each key pair can be limited to the places you use it. Choose Edit access on the key in the API Keys page, then pick who may use each half.
Public key access, for the key in your store's embed code:
- Stylor only: only Stylor itself, meaning the dashboard's Playground, previews and Stylor's own services. No website or app can use it, including your store.
- Allowed websites: only the sites you list, as
store.com, or*.store.comfor the domain and every subdomain (www.store.com,eu.store.com). Allow localhost lets pages on your own computer use the key while you build. Allow apps and servers lets requests that come from no website use it, such as a mobile app; browsers always say which site a request comes from, apps and servers don't. Other websites can neither show your widget nor spend your quota. - Everyone: any website or app.
Private key access, for your servers: Stylor only, Allowed IP addresses (addresses and ranges such as 203.0.113.7 or 203.0.113.0/24, each with a note), or Everyone.
A request from anywhere else fails with 403 and a message saying where it came from. Changes take effect within five minutes. When a website on neither list keeps being refused, the key shows it, with Add and Ignore.
Your organization's keys
- The primary key comes with your organization. It is set to Stylor only and cannot be deleted; rotate it if you need new values.
- The Storefront key is made when you connect your first store, limited to that store's domains, and is the key in your embed code. Connecting another store adds its domains to it, and deleting a store removes them. It is otherwise an ordinary key.
- Organizations created before this keep their existing keys as they were, so live embeds keep working.
Authentication errors
All authentication failures return a JSON body of the form { "error": "<message>" }. These are the messages you can receive before an endpoint runs.
| Status | Message | Cause |
|---|---|---|
| 401 | API key missing. |
The Authorization header is absent, empty, or the key does not have three dash-separated segments. |
| 401 | Authentication failed: public key is invalid or not recognized. |
A public-key endpoint received a key that does not exist, for example a deleted key. |
| 401 | Authentication failed: private key provided instead of a public key. |
A public-key endpoint received an sgpt-sk-… key. |
| 401 | Authentication failed: public key provided instead of a private key. |
A private-key endpoint received an sgpt-pk-… key. |
| 401 | Authentication failed: bearer token format is invalid. |
A private key was sent without its :: segment. |
| 401 | Authentication failed: token is not recognized. |
A private key's lookup segment does not match any key. |
| 401 | Authentication failed: private key is invalid. |
A private key's secret does not match. |
| 401 | Authentication failed: API key could not be read. Regenerate the key. |
The organization data embedded in the key could not be read. Create a new key. |
| 403 | No active subscription for this organization. |
The key's organization has no active subscription. |
| 403 | This API key cannot be used from <origin>. … |
The public key is limited to its websites, and the request came from a site not on the list. |
| 403 | This API key only accepts requests from its allowed websites. … |
The public key is limited to its websites, refuses apps and servers, and the request came from no website. |
| 403 | This API key cannot be used from <address>. … |
The private key is limited to its IP addresses, and the request came from another. |
| 403 | This API key is for Stylor's own use only. … |
The key's access is set to Stylor only. Use another key, such as your Storefront key. |
If the organization that owns a key has been deleted, endpoints that look it up reject the key with 401.
For quota and entitlement errors (403 and 429), see Rate limits and quotas.
Rotating keys
Rotate a key on a schedule, whenever someone with access leaves, and at once if you suspect it has leaked. Choose Rotate on the key in the API Keys page and type its name to confirm.
Rotating gives the key new public and private values and keeps everything else: its name, its allowed websites and IP addresses. The old values stop working immediately, so have the new ones ready to deploy:
- Rotate the key and copy both new values. The private key is shown only once.
- Put the new public key in your store's embed code and any client code, and the new private key in your servers.
Every organization has one primary key, the one it was created with. It can be rotated but not deleted. Other keys can be deleted; a deleted key stops working immediately. To move traffic without any gap, create a second key, deploy it, then delete or rotate the old one.
Good practices
- Load keys from environment variables such as
STYLOR_API_KEYrather than hard-coding them. - Use separate key pairs for separate environments or services, so you can revoke one without affecting the others.
- Call private-key endpoints only from your backend. If browser code needs catalogue management, proxy it through your server.
- Don't log full
Authorizationheaders.