Skip to main content
This page follows the auth.md convention so an agent can read it as a markdown walkthrough at https://docs.wisepim.com/auth.md. It describes what exists today, including what is not available, so that nobody has to guess.

​
Discover

WISEPIM has two ways in, for two audiences: There is no agent_auth block, no identity_endpoint and no published /.well-known/oauth-authorization-server or /.well-known/oauth-protected-resource yet. The Public API does not accept OAuth tokens, and the assistant connection is not an open authorization server: today it is available to ChatGPT and Codex. Neither identity_assertion (ID-JAG) nor service_auth is supported.

​
Pick a method

  • You run the code and a person can create a key: use a project API key. This is the method for every integration with the Public API.
  • You are an assistant a WISEPIM user wants to connect: use Connected Apps if you are ChatGPT or Codex. Otherwise ask the user to create a project API key with the scopes you need and hand it to your server-side code.
  • You only need documentation: the docs MCP server at https://docs.wisepim.com/mcp needs no credential at all.

​
Register

Project API keys have no programmatic registration. A project owner or admin signs in to the WISEPIM app, opens Settings > API Access, clicks Create API key, names it and selects scopes: Scopes are fixed when the key is created and cannot be widened later. A project holds at most 25 active keys, and one person at most 10 per project. API access depends on the plan; see pricing. For Connected Apps, the assistant starts the OAuth request with response_type=code, a code_challenge (S256), the resource it wants to reach and the scopes it needs. The user is sent to a consent screen in the app that names the assistant and the account, lists each requested permission in plain language, and asks them to choose exactly one project.

​
Claim

A project API key is claimed by the human who created it: the full wpk_... value is shown once, right after creation. WISEPIM stores only a hash. The key then has to be placed in the integration’s secrets manager or environment by a person. A Connected Apps grant is claimed when the user clicks Allow access on the consent screen. Deny access ends the flow.

​
Exchange

There is no exchange step for a project API key: the key is the bearer credential, and no refresh token exists. If the key is lost, revoke it and create a new one. For Connected Apps, the assistant exchanges the authorization code for an access token with its PKCE verifier, as in any OAuth 2.0 authorization-code flow. The token is scoped to the one project the user picked and to the approved permissions.

​
Use the access_token

Send the key on every request:
GET /me needs no scope and returns the key’s scopes, its rate limit and the bound project, so an agent can verify what it holds before doing anything else. Every other endpoint is listed in the API reference. Rate limit: 600 requests per minute per key by default, with X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on every response. A connected assistant uses its access token against the product MCP server. Reads return data. Every write starts as a proposal that freezes the exact change; by default the assistant applies it within the granted scopes, and when the user switched on approval for the connection, the proposal waits for the user’s field-by-field review in WISEPIM before it can be applied. Every preview tells the assistant which policy applies.

​
Errors

All errors are JSON: {"error": "...", "code": "...", "request_id": "..."}. Branch on code.

​
Revocation

  • Project API keys: a project owner or admin clicks Revoke under Settings > API Access. Revocation applies on the next request; nothing is cached. Keys also stop when their creator loses access to the project or is deactivated, and on their expiry date if one was set.
  • Connected Apps: the user opens Settings > Connected apps and revokes the connection. The assistant loses access immediately, and pending proposals expire on their own.