Getting started
Authorization & consent
Connections are authorized with OAuth 2.1 — the client registers itself, you approve in the browser, and the tokens it receives carry exactly the tier you chose. There is no API key to copy around, and nothing to configure ahead of time.
The OAuth 2.1 flow
- The client fetches the well-known metadata (below), discovers the authorization server, and registers itself via RFC 7591 dynamic client registration — no pre-shared client id.
- It starts an authorization code flow with PKCE (S256 required) and opens your browser on Peak PIM's consent page.
- You sign in to Peak PIM if you aren't already — the account you're signed in to is the account the connection is bound to — and pick a permission tier (or deny).
- The client exchanges the code for an access token and a refresh token scoped to that tier, and starts calling tools.
Discovery endpoints
Standard discovery is in place — most clients need only the connector URL:
/.well-known/oauth-protected-resource | RFC 9728 protected-resource metadata (also advertised by the /mcp 401 challenge) |
/.well-known/oauth-authorization-server | RFC 8414 authorization-server metadata |
/oauth/register | RFC 7591 dynamic client registration |
/oauth/authorize · /oauth/token | Authorization code + refresh token, PKCE S256 required |
All relative to https://api.peak-pim.com.
The consent page
The browser consent screen shows who is asking and offers up to three permission tiers. The tier you pick determines the scopes on every token the connection will ever hold:
| Tier | Scopes granted | Allows |
|---|---|---|
Read read | pim:read | Browse and compare the catalog. Nothing can be changed. |
Read & write read_write | pim:read pim:write | Also edit draft values — nothing reaches Shopify until a person (or a publish-tier connection) publishes. |
Read, write & publish read_write_publish | pim:read pim:write pim:publish | Also push items live to your Shopify stores. |
The pim:publish scope can only be granted through this consent screen — never through any other credential surface. And no tool deletes data: a delete permission is not grantable at all.
A tool call outside the granted tier fails with a 403 permission error and re-authorization guidance — the assistant is told which tier it would need.
The tier is fixed per connection
A connection's tier is set when you approve it and never changes silently. To upgrade or downgrade, disconnect the client (in Peak PIM or in the client itself), then reconnect and pick the new tier at the consent screen.
Token lifetimes & revocation
| Token | Lifetime | Notes |
|---|---|---|
| Access token | ~7 days | Sent as the bearer on every tool call. |
| Refresh token | ~30 days | Lets the client re-mint access tokens without re-consent — at the same tier only. |
Every request re-validates the token with a live lookup, so revocation is immediate: a revoked connection's very next tool call fails, with no grace window.
Managing connections
Settings → AI assistants (MCP) in Peak PIM lists every authorized connection. From there you can disconnect one client or revoke everything at once. Revocation also invalidates refresh tokens, so a revoked connection cannot silently re-mint access — the next tool call fails and the client must re-authorize through consent.