> For the complete documentation index, see [llms.txt](https://docs.globo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.globo.io/api-reference/api-access-and-authentication.md).

# API access & authentication

Generate an API token to call the app's filter, search, and settings data directly from your own code, for custom storefronts and integrations.

## What this does

Generates a personal access token that lets your own code call the app's filter, search, and settings data directly over HTTPS — useful for a custom/headless storefront, a server-side integration, or any tooling that needs live filter and product data outside of the app's own storefront widget.

## Generate a token

1. In the app, go to **Settings > API access**.
2. Click **Create token**.
3. Give it a **Name** (for your own reference — e.g. "Headless storefront").
4. Choose which **scopes** it needs: **read:catalog** (filter and search data) and/or **read:config** (app settings).
5. Choose an **expiration**: 3 months, 9 months, 1 year (default), or never.
6. Click **Create**. The full token is shown once — copy it now, since you won't be able to see it again after closing the dialog.

You can have up to 10 active tokens per store at a time.

\[SCREENSHOT: Settings > API access — token table and Create token modal]

## Authenticate a request

Send the token as a Bearer token in the `Authorization` header of every request:

```
Authorization: Bearer glb_sfs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

All endpoints are relative to your store's base URL, shown on the **API access** page:

```
https://{your-app-server}/sfs/v1
```

You don't need to (and can't) pass a `shop` parameter yourself — the token already identifies which store the request is for.

## Scopes

Each token is granted one or both scopes when it's created:

| Scope          | Grants access to             |
| -------------- | ---------------------------- |
| `read:catalog` | `GET /filter`, `GET /search` |
| `read:config`  | `GET /settings`              |

Calling an endpoint with a token that doesn't have the required scope returns a `403`.

## Managing tokens

On the **API access** page, each token shows its name, prefix (the first few characters — the full secret is never shown again), scopes, expiration, last-used time, and status. Use **Rotate** to issue a new token with the same name/scopes/expiration while immediately invalidating the old one (useful if a token may have leaked), or **Revoke** to disable a token permanently.

## Errors

Authentication and rate-limit errors use the same shape on every endpoint: `{"success": false, "message": "..."}`. An individual endpoint's own business-logic errors (for example, an unrecognized `form_id` on `GET /filter`) may use a different shape — see that endpoint's own Errors section.

| Status | Cause                                                                         |
| ------ | ----------------------------------------------------------------------------- |
| `401`  | Missing `Authorization` header, or the token is invalid, revoked, or expired. |
| `403`  | Token doesn't have the required scope, or the store is currently unavailable. |
| `422`  | Request parameters failed validation.                                         |
| `429`  | Too many requests — see Rate limits below.                                    |

## Rate limits

Requests are throttled per store. If you exceed the limit, you'll get a `429` response with `Retry-After`, `X-RateLimit-Limit`, and `X-RateLimit-Remaining` headers — back off and retry after the time indicated.

## Related pages

* [Get filtered products](/api-reference/get-filter-products.md)
* [Search products](/api-reference/search-products.md)