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.

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 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 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: 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: 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.