> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wisepim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and scopes

> Authenticate WISEPIM Public API calls with a project API key, choose least-privilege scopes, handle 401 and 403 responses, and rotate or revoke keys.

Every request to the WISEPIM Public API carries a **project API key** as a bearer token. There is no OAuth flow, no session and no other sign-in step for the API: the key is the credential.

```bash theme={null}
curl https://wisepim.com/api/public/v1/project \
  -H "Authorization: Bearer wpk_..."
```

## How keys work

* **One key, one project.** A key is bound to the project it was created in and can never reach another project. A product id from another project is a `404`, not a `403`.
* **Scopes are fixed at creation.** You choose the permissions when you create the key. They cannot be widened afterwards; create a new key instead.
* **Keys act on behalf of the person who created them.** Every request re-checks that this person is still active and still has access to the project. Write scopes also require that they can still edit the project. Off-board the person and their keys stop with them.
* **Only the prefix is stored.** WISEPIM keeps a hash of the key, so the full `wpk_...` value is shown exactly once, right after creation or rotation.
* **Revocation and expiry apply on the next request.** Nothing is cached.

Keys are created under **Settings > API Access** by project owners and admins. See [API Access](https://docs.wisepim.com/en/settings/api.md) for the walkthrough and the limits per project and per person.

## Scopes

Request the smallest set that does the job. Reads and writes are separate scopes.

| Scope | Grants | Used by |
| - | - | - |
| `project:read` | The project's name, languages, industry and limits | [`GET /project`](https://docs.wisepim.com/en/api-reference/key/project) |
| `products:read` | Products with attribute values and category links | [`GET /products`](https://docs.wisepim.com/en/api-reference/products/list), [`GET /products/{product_id}`](https://docs.wisepim.com/en/api-reference/products/get) |
| `products:write` | Create products and update names, descriptions, identifiers, prices, SEO fields, categories and attribute values | [`POST /products`](https://docs.wisepim.com/en/api-reference/products/create), [`PATCH /products/{product_id}`](https://docs.wisepim.com/en/api-reference/products/update), [`POST /products/batch`](https://docs.wisepim.com/en/api-reference/products/batch) |
| `categories:read` | The project's category tree | [`GET /categories`](https://docs.wisepim.com/en/api-reference/categories/list), [`GET /categories/{category_id}`](https://docs.wisepim.com/en/api-reference/categories/get) |
| `attributes:read` | The project's attribute definitions | [`GET /attributes`](https://docs.wisepim.com/en/api-reference/attributes/list), [`GET /attributes/{attribute_id}`](https://docs.wisepim.com/en/api-reference/attributes/get) |

[`GET /me`](https://docs.wisepim.com/en/api-reference/key/me) needs no scope. Call it first to confirm which key you are holding, which scopes it carries and which project every other call will land in.

The same scope names appear in the [OpenAPI spec](https://docs.wisepim.com/openapi.json): each operation lists its scope under `x-required-scopes`, and the `ProjectApiKeyAuth` security scheme describes the full catalogue under `x-scopes`.

## Authentication errors

| Response | Cause | What to do |
| - | - | - |
| `401 api_key_required` | No `Authorization` header, a value that does not start with `wpk_`, or a key that was revoked or has expired | Check the header, then check the key's state under Settings > API Access |
| `403 insufficient_scope` | The key lacks the scope the endpoint needs. The body lists `required_scopes` and `missing_scopes` | Create a key with the right scopes; scopes on an existing key cannot change |
| `403 issuer_cannot_write` | The person who created the key can no longer edit the project | Have a project owner or admin create a replacement key |
| `429 rate_limited` | More than the key's per-minute limit, 600 by default | Wait for `Retry-After` seconds, then continue. Spread bulk work with `POST /products/batch` |

## Keep keys safe

* Send keys from your server, never from browser code, mobile apps or public repositories.
* Store them in environment variables or a secrets manager, not in source control.
* Give each integration its own key so you can revoke one without breaking the others.
* Check each key's **Last used** date under Settings > API Access and revoke keys that are no longer in use.
* If a key may have leaked, create a replacement, switch the integration to it, then **Revoke** the old one. Revocation is immediate.

## For AI assistants

Project API keys are for code you run yourself. To let ChatGPT or Codex work with a catalog, connect it through [Connected Apps](https://docs.wisepim.com/en/settings/connected-apps.md): the assistant asks for named permissions, you approve exactly one project, and you choose whether its changes apply directly or wait for your review in WISEPIM. That connection is granted and revoked in the app, not with an API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.