Tokens and OAuth connections API reference
List, create, and revoke API tokens, and list or disconnect hosted MCP OAuth clients.
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.
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:
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:
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:
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:
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:
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.