Tokens and OAuth connections API reference
List your API tokens, create or revoke them from a signed-in dashboard session, 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 Accept: application/json; JSON creation uses Content-Type: application/json. These routes have no teamPid path segment, and they share the user-route limit of 60 requests per minute.
| Operation | Who can call it |
|---|---|
GET /tokens | Any API token for the account, whatever its abilities, or a signed-in dashboard session. |
POST /tokens | A signed-in dashboard session only, with a recently confirmed password. |
DELETE /tokens/{tokenId} | A signed-in dashboard session only. |
GET /oauth-connections | An API token with read or write, or a signed-in dashboard session. |
DELETE /oauth-connections/{clientId} | An API token with write, or a signed-in dashboard session. |
An API token can't create or revoke tokens, even a full-access one, so a leaked token can't make a broader one or revoke the others. It gets 403 with message: "API tokens can't use this endpoint. Sign in to the dashboard to do this.". The API & AI access page in the dashboard makes these calls for you; see Create and revoke API tokens. The OpenAPI reference marks both operations x-rightmessage-session-only.
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. Only a signed-in dashboard session can call it; an API token gets 403. The account must have API access. If it does not, the endpoint returns 403 with message: "API access is included on the Scale plan and above.".
The session also needs a recently confirmed password. Until it has one, the endpoint returns 423, and the dashboard asks you to Confirm your password (POST /user/confirm-password) before it tries again.
| 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. The dashboard's Create token sends only name, so tokens it creates have ["*"].
Illustrative body 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. Only a signed-in dashboard session can call it; an API token gets 403.
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.
GET /oauth-connections
Lists the user's authorized OAuth clients and their connection metadata. An API token needs read or write.
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. An API token needs write.
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. An API token on a session-only operation, or one without the ability an OAuth connection operation needs, gets 403 with a message that says why. Suspended accounts return 403 and invalidate the presented token. Token creation without a recently confirmed password returns 423. 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.