API access and authentication
The Productmind REST API is the API the Productmind app itself runs on, so anything you can do in the app, a script or tool of yours can do through it. Every request carries an access token that a person authorized in their browser. There are no API keys and no personal access tokens: your tool signs in with OAuth 2.1 and PKCE, the same way the Productmind CLI and AI assistants do.
Key concepts
Base URL. Every endpoint is under https://api.productmind.ai. The
API Reference lists them all.
Client. The script or tool that calls the API. Before it can ask for a token, it needs a client ID, which it gets by registering itself.
Access token. A bearer token sent with every request, valid for one hour.
Refresh token. A token your client trades for a new access token when the old one expires. Each trade gives a new refresh token too, and a refresh token expires 90 days after it was issued.
Organization. A token works in one organization: the one the person chose when they authorized it.
Workspace-scoped paths. Almost every endpoint lives under
/workspaces/{workspaceId}/..., so a request names the workspace it is about.
How a client gets a token
Productmind uses the OAuth 2.1 authorization code flow with PKCE:
- Your client registers itself and receives a client ID.
- It opens the person's browser on the authorization endpoint.
- The person signs in to Productmind and, if they belong to several organizations, chooses one.
- The browser returns to your client with an authorization code.
- Your client exchanges the code for an access token and a refresh token.
Your client finds every endpoint it needs in Productmind's authorization server metadata:
Code
| Endpoint | Address |
|---|---|
| Authorization | https://api.productmind.ai/auth/authorize |
| Token | https://api.productmind.ai/auth/token |
| Registration | https://api.productmind.ai/auth/register |
| Revocation | https://api.productmind.ai/auth/revoke |
The only supported PKCE method is S256. Productmind doesn't use scopes to limit a token: what
it can do is decided by the person's role.
Many OAuth libraries can run the sign-in from the metadata address. If you only want to use Productmind from an AI assistant, you don't need any of this: see AI assistants (MCP).
Getting a token
To register your client
Send your client's name and the address the browser should return to:
Code
The response carries your client_id. Registration needs no account.
Keep the client_id and use it for every later sign-in. A client ID that nobody has signed in
with is removed after a day. The authorization endpoint still accepts it after that: it registers
the client ID again, with the redirect_uri you send, under the same rules as registration. The
client_name isn't kept, so Connected clients then lists the connection by its client ID.
The name can be up to 200 characters, and you can register up to 10 return addresses of up to 2,048 characters each. A larger registration is refused.
The return address must be one only the person's own machine can receive:
- a loopback address,
127.0.0.1,::1orlocalhost, over plainhttp. The port can change from run to run, so your client can listen on any free port; - or a browser extension's callback address.
Any other address is refused with "redirect_uris must be a loopback address
(http://127.0.0.1:<port>/...) or a browser-extension callback". So a web application running
on your own servers can't sign people in to Productmind.
The Productmind CLI is registered in advance, and doesn't register itself. AI assistants such as Claude Code, Codex and GitHub Copilot may register themselves each time they connect.
To get an access token
-
Create a PKCE code verifier, a random string of 43 to 128 characters that uses only
A-Z,a-z,0-9,-,.,_and~, and itsS256code challenge. -
Open the person's browser on the authorization endpoint:
Code -
The person signs in to Productmind. If they belong to several organizations, they choose one and choose Continue. They have 10 minutes.
-
The browser returns to your
redirect_uriwithcodeandstate. Check thatstateis the value you sent. -
Exchange the code at the token endpoint:
Code
The response carries access_token, refresh_token, expires_in (in seconds) and
token_type Bearer. Keep both tokens somewhere safe: anyone who holds them can act as the
person who signed in.
To refresh the access token
When the access token expires, trade the refresh token for a new pair:
Code
The response is the same standard body as the code exchange: access_token, refresh_token,
expires_in, token_type and scope. The same fields are also repeated inside a data field,
for integrations written when the response had only that shape; new code should read the
top-level fields.
Each refresh token works once. Store the new refresh token and use it next time. If a client refreshes twice at the same moment, or retries a refresh whose response it lost, both requests succeed within a minute of the first and return the same new refresh token. A refresh token used again more than a minute after it was exchanged is treated as stolen: Productmind ends that sign-in, and the person has to connect your client again.
To revoke a token
When your client no longer needs access, for example when someone signs out of it:
Code
Productmind ends that sign-in, including the access tokens issued from it. The endpoint always answers with success, even for a token it doesn't know.
The person can also revoke your client themselves: in their profile, under
Connected clients, it is listed as MCP: followed by the client_name you registered, and
Revoke ends it.
See Profile and notifications.
Calling the API
Send the access token in the Authorization header:
Code
This lists the workspaces the person can use in the token's organization. Take a workspace's
id from it and use it in the workspace-scoped paths, for example:
Code
A successful response carries its result in a data field. A list may also carry
pagination. The API Reference documents every endpoint's parameters and responses.
How tokens behave
A token acts as the person who authorized it. It holds their role in the organization, plus the permissions their teams add. A request their role doesn't allow is refused, just as the app would refuse the same action. If an Owner or Admin changes their role, the token follows the change. See Roles and permissions.
A token reaches the workspaces the person can use. Owners and Admins get every workspace, and other members only the workspaces they have been given. See Organizations and workspaces.
A token works in one organization. To work in another organization, authorize again and choose it.
Sign-ins end. A refresh is refused, and the person must authorize again, when:
- the refresh token is more than 90 days old;
- the sign-in was revoked, by your client or from Connected clients;
- the person changed or reset their password, turned on two-factor authentication, or signed out their other sessions;
- the person was disabled or left the organization;
- the organization was suspended.
A refused refresh answers 401 with "error": "invalid_grant" in its body, the standard OAuth
answer, so your client can tell it from a network failure and ask the person to authorize again.
When the organization is suspended it answers 403 instead.
What a token does is recorded as the person. Changes made through the API show the person as their author, and appear under their name in the audit log.
Permissions
| To | You need |
|---|---|
| Authorize a client | A Productmind account in the organization |
| Call an endpoint | The permission the same action needs in the app, for example Tasks: Read to list tasks |
Troubleshooting
"Invalid redirect_uri"
The redirect_uri you sent to the authorization endpoint isn't one your client registered. The
scheme, host and path must match exactly. Only the port of a loopback address may differ.
"code_challenge_method is required and must be 'S256'. 'plain' is not supported."
Send code_challenge_method=S256, with a challenge made from your verifier with SHA-256.
"Unknown client_id"
The client ID you sent to the authorization endpoint isn't one Productmind issued, for example
because it was cut short. Send the whole client_id from the registration response. A client ID
removed after a day unused answers this too when the redirect_uri you send isn't one
registration accepts.
The token exchange answers "invalid_grant"
The response's error_description names the cause. It is one of these:
- the code was already used, or more than 10 minutes have passed since you opened the authorization endpoint;
- the
client_idorredirect_uriisn't the one you sent to the authorization endpoint; - the code doesn't match the
code_verifieryou sent; - the person signed out of the browser session that approved your client before you exchanged the code, for example by changing or resetting their password;
- the person's account is disabled, or they are no longer an active member of the organization they chose.
Start the authorization again.
A request answers 401
The access token has expired or the sign-in was revoked. Refresh the token, or authorize again if the refresh is refused.
A request answers 403
The person's role doesn't allow that action, they can't use that workspace, or the organization's
plan doesn't include the feature (the message names it). Check the workspaces the token can reach
with GET /workspaces. For a feature the plan doesn't include, see
Features that depend on your plan.