> ## 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, writes, deletion, execution and cancellation are separate scopes. Existing keys gain no new permissions when the API expands. Rotation preserves scopes; create a replacement key to grant additional permissions.

Scopes do not override the issuer’s current role, field permissions or prompt ownership. All mutation scopes require edit access, and resource management retains its corresponding role permissions.

| Scope | Grants |
| - | - |
| `project:read` | Read the project's identity, locales and limits. |
| `products:read` | List and read products, including attribute values and category membership. |
| `products:write` | Create and update products and their catalogue content. |
| `products:delete` | Delete products from this project. |
| `categories:read` | List the project's category tree. |
| `categories:write` | Create and update the project's categories. |
| `categories:delete` | Delete the project's categories. |
| `attributes:read` | List the project's attribute definitions. |
| `attributes:write` | Create and update the project's attribute definitions. |
| `attributes:delete` | Delete the project's attribute definitions. |
| `attribute-groups:read` | Read the project's attribute groups. |
| `attribute-groups:write` | Create and update the project's attribute groups. |
| `attribute-groups:delete` | Delete the project's attribute groups. |
| `product-families:read` | Read the project's product families. |
| `product-families:write` | Create and update the project's product families. |
| `product-families:delete` | Delete the project's product families. |
| `family-attributes:read` | Read the project's family attribute bindings. |
| `family-attributes:write` | Create and update the project's family attribute bindings. |
| `family-attributes:delete` | Delete the project's family attribute bindings. |
| `product-categories:read` | Read the project's product category memberships. |
| `product-categories:write` | Create and update the project's product category memberships. |
| `product-categories:delete` | Delete the project's product category memberships. |
| `value-code-sets:read` | Read the project's controlled vocabularies. |
| `value-code-sets:write` | Create and update the project's controlled vocabularies. |
| `value-code-sets:delete` | Delete the project's controlled vocabularies. |
| `code-set-values:read` | Read values in the project's controlled vocabularies. |
| `code-set-values:write` | Create and update values in the project's controlled vocabularies. |
| `code-set-values:delete` | Delete values in the project's controlled vocabularies. |
| `uom-code-sets:read` | Read the project's unit-of-measure sets. |
| `uom-code-sets:write` | Create and update the project's unit-of-measure sets. |
| `uom-code-sets:delete` | Delete the project's unit-of-measure sets. |
| `uom-values:read` | Read units in the project's unit-of-measure sets. |
| `uom-values:write` | Create and update units in the project's unit-of-measure sets. |
| `uom-values:delete` | Delete units in the project's unit-of-measure sets. |
| `prompts:read` | Read prompts visible to the key issuer in this project. |
| `prompts:write` | Create prompts and update the key issuer's own prompts in this project. |
| `prompts:delete` | Delete the key issuer's own prompts in this project. |
| `knowledge-libraries:read` | Read this project's knowledge library. |
| `knowledge-libraries:write` | Create and update this project's knowledge library. |
| `knowledge-libraries:delete` | Delete this project's knowledge library. |
| `keywords:read` | Read the project's keywords. |
| `keywords:write` | Create and update the project's keywords. |
| `keywords:delete` | Delete the project's keywords. |
| `dictionary-entries:read` | Read the project's translation dictionary entries. |
| `dictionary-entries:write` | Create and update the project's translation dictionary entries. |
| `dictionary-entries:delete` | Delete the project's translation dictionary entries. |
| `import-templates:read` | Read the project's reusable import templates. |
| `import-templates:write` | Create and update the project's reusable import templates. |
| `import-templates:delete` | Delete the project's reusable import templates. |
| `export-templates:read` | Read the project's reusable export templates. |
| `export-templates:write` | Create and update the project's reusable export templates. |
| `export-templates:delete` | Delete the project's reusable export templates. |
| `enrichment:execute` | Start product enrichment using this project's native pipelines and credit limits. |
| `translations:execute` | Start product translation using this project's native pipelines and credit limits. |
| `bulk-actions:execute` | Start bulk actions against this project's products. |
| `jobs:read` | Read this project's background job status and progress. |
| `jobs:cancel` | Request cooperative cancellation of this project's background jobs. |

[`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.