# Tokens and OAuth connections API reference

List, create, and revoke API tokens, and list or disconnect hosted MCP OAuth clients.

Available on the Scale and Pro plans.

These endpoints manage credentials for the authenticated user. They do not edit a project draft. Token deletion and OAuth disconnection take effect immediately.

## Authentication and scope

The base URL is `https://api.rightmessage.com/v1`. Send `Authorization: Bearer YOUR_API_TOKEN` and `Accept: application/json`. JSON creation uses `Content-Type: application/json`. These routes have no `teamPid` path segment.

All five operations require API-token authentication and share the user-route limit of 60 requests per minute. REST abilities do not restrict these routes. A token marked `read` can still manage tokens, including creating one when the account has API access. See [abilities and their limits](https://rightmessage.com/help/rest-api-overview#abilities-and-their-limits).

## GET /tokens

Lists API token metadata without exposing token secrets.

No parameters. Returns 200 with `data`, an array of the user's token metadata. Each item contains numeric `id`, string `name`, string-array `abilities`, nullable datetime `last_used_at`, and datetime `created_at`. It never returns token secrets.

Illustrative request and response, not executed:

```http
GET /v1/tokens HTTP/1.1
Host: api.rightmessage.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
```

```json
{"data":[{"id":42,"name":"WorkForge reporting","abilities":["read"],"last_used_at":null,"created_at":"2026-10-13T12:00:00.000000Z"}]}
```

## POST /tokens

Creates a token for the authenticated user. The account must have API access. If it does not, the endpoint returns 403 with `message: "API access requires the Scale plan or higher."`.

| Body field  | Contract                                                                                                              |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `name`      | Required nonempty string, maximum 255 characters                                                                      |
| `abilities` | Optional array, default `["*"]`. Each item must be `read`, `write`, `publish`, or `*`. No minimum length is enforced. |

Returns 201 with `data.id`, `data.name`, `data.abilities`, and `data.plainTextToken`. The complete token is returned at creation only. The request has no expiration or project-scope field.

Illustrative request and response, not executed. The secret below is deliberately not a usable credential:

```http
POST /v1/tokens HTTP/1.1
Host: api.rightmessage.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
Content-Type: application/json

{"name":"WorkForge reporting","abilities":["read"]}
```

```json
{"data":{"id":42,"name":"WorkForge reporting","abilities":["read"],"plainTextToken":"ILLUSTRATIVE_NOT_A_REAL_TOKEN"}}
```

## DELETE /tokens/{tokenId}

Revokes one of the authenticated user's API tokens.

`tokenId` is the numeric ID from the token list, not the secret. No body. Deletes only a token belonging to the authenticated user. Returns 204 with no body. Unknown or another user's token returns 404. Deleting the token used for this request revokes it for subsequent requests.

Illustrative request, not executed:

```http
DELETE /v1/tokens/42 HTTP/1.1
Host: api.rightmessage.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
```

Illustrative response: `204 No Content`, empty body.

## GET /oauth-connections

Lists the user's authorized OAuth clients and their connection metadata.

No parameters. Returns 200 with `data`, an array sorted by client name. Only non-revoked access tokens qualify. An expired access token can still appear when it has an unrevoked, unexpired refresh token.

Tokens are grouped by client. Each connection contains string `client_id`, string `client_name`, datetime `connected_at`, and datetime `expires_at`. Connection time comes from the earliest qualifying token. Name comes from the latest-created qualifying token's client, falling back to `Unknown client`. Expiry uses the maximum associated refresh-token expiry when one exists; otherwise it uses the latest-created qualifying access token's expiry, not necessarily the maximum access-token expiry. The refresh-expiry calculation does not separately exclude revoked refresh tokens attached to otherwise qualifying access tokens.

Illustrative request and response, not executed:

```http
GET /v1/oauth-connections HTTP/1.1
Host: api.rightmessage.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
```

```json
{"data":[{"client_id":"workforge-client","client_name":"WorkForge assistant","connected_at":"2026-10-13T12:00:00.000000Z","expires_at":"2026-11-12T12:00:00.000000Z"}]}
```

## DELETE /oauth-connections/{clientId}

Disconnects an OAuth client by revoking the user's tokens for that client.

`clientId` is the exact string from the connection list. No body. The operation revokes all this user's unrevoked access tokens for that client and each associated refresh token together. This includes expired access tokens that remain unrevoked. It does not delete a project or affect another user's connection.

Returns 204 with no body. Returns 404 when no unrevoked tokens exist for this user and client. The user must authorize the client again to reconnect.

Illustrative request, not executed:

```http
DELETE /v1/oauth-connections/workforge-client HTTP/1.1
Host: api.rightmessage.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
```

Illustrative response: `204 No Content`, empty body.

## Common errors

Unauthenticated requests return 401. Suspended accounts return 403 and invalidate the presented token. Invalid creation fields return 422 with `message` and a field-keyed `errors` map. Throttled requests return 429. Maintenance returns 503. No operation here requires publishing.