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

<Availability permission="Any role. A token can do exactly what the person who authorized it can do." />

## Key concepts

**Base URL.** Every endpoint is under `https://api.productmind.ai`. The
[API Reference](/api) 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](#to-register-your-client).

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

1. Your client registers itself and receives a client ID.
2. It opens the person's browser on the authorization endpoint.
3. The person signs in to Productmind and, if they belong to several organizations, chooses one.
4. The browser returns to your client with an authorization code.
5. 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:

```text
https://api.productmind.ai/.well-known/oauth-authorization-server
```

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

:::tip
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)](/user-guide/tools/ai-assistants).
:::

## Getting a token

### To register your client

Send your client's name and the address the browser should return to:

```bash
curl -X POST https://api.productmind.ai/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My release script",
    "redirect_uris": ["http://127.0.0.1:8765/callback"],
    "grant_types": ["authorization_code", "refresh_token"],
    "response_types": ["code"],
    "token_endpoint_auth_method": "none"
  }'
```

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`, `::1` or `localhost`, over plain `http`. 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

1. Create a PKCE code verifier, a random string of 43 to 128 characters that uses only
   `A`-`Z`, `a`-`z`, `0`-`9`, `-`, `.`, `_` and `~`, and its `S256` code challenge.
2. Open the person's browser on the authorization endpoint:

   ```text
   https://api.productmind.ai/auth/authorize?response_type=code
     &client_id=<client_id>
     &redirect_uri=http://127.0.0.1:8765/callback
     &code_challenge=<code_challenge>
     &code_challenge_method=S256
     &state=<random value>
   ```

3. The person signs in to Productmind. If they belong to several organizations, they choose one
   and choose **Continue**. They have 10 minutes.
4. The browser returns to your `redirect_uri` with `code` and `state`. Check that `state` is the
   value you sent.
5. Exchange the code at the token endpoint:

   ```bash
   curl -X POST https://api.productmind.ai/auth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d grant_type=authorization_code \
     -d client_id=<client_id> \
     -d code=<code> \
     -d code_verifier=<code_verifier> \
     -d redirect_uri=http://127.0.0.1:8765/callback
   ```

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:

```bash
curl -X POST https://api.productmind.ai/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token=<refresh_token>
```

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:

```bash
curl -X POST https://api.productmind.ai/auth/revoke \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d token=<refresh_token>
```

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](/user-guide/profile-and-notifications).

## Calling the API

Send the access token in the `Authorization` header:

```bash
curl https://api.productmind.ai/workspaces \
  -H "Authorization: Bearer <access_token>"
```

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:

```bash
curl https://api.productmind.ai/workspaces/<workspaceId>/tasks \
  -H "Authorization: Bearer <access_token>"
```

A successful response carries its result in a `data` field. A list may also carry
`pagination`. The [API Reference](/api) 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](/user-guide/reference/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](/user-guide/get-started/organizations-and-workspaces#key-concepts).

**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](/user-guide/settings/identity-and-access/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_id` or `redirect_uri` isn't the one you sent to the authorization endpoint;
- the code doesn't match the `code_verifier` you 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](/user-guide/reference/plans-and-limits#features-that-depend-on-your-plan).

## Related topics

- [API Reference](/api)
- [AI assistants (MCP)](/user-guide/tools/ai-assistants)
- [Productmind CLI](/user-guide/tools/productmind-cli)
- [Roles and permissions](/user-guide/reference/roles-and-permissions)
