---
title: RightMessage auth.md
description: "How an agent authenticates to RightMessage: hosted OAuth for the MCP server, personal API tokens for the REST API."
canonical: https://rightmessage.com/auth.md
name: rightmessage-auth
resource: https://api.rightmessage.com/mcp/rightmessage
authorization_server: https://api.rightmessage.com
protected_resource_metadata: https://api.rightmessage.com/.well-known/oauth-protected-resource/mcp/rightmessage
api_base_url: https://api.rightmessage.com/v1
openapi: https://api.rightmessage.com/openapi.json
agent_registration: not_supported
---

# RightMessage auth.md

You are an agent. RightMessage has two authenticated surfaces, and each takes a different credential:

| Surface | URL | Credential |
| --- | --- | --- |
| MCP server (Streamable HTTP) | `https://api.rightmessage.com/mcp/rightmessage` | Hosted OAuth access token with scope `mcp:use`, **or** a personal API token |
| REST API v1 | `https://api.rightmessage.com/v1` | Personal API token **only** — OAuth access tokens are rejected |

RightMessage does **not** implement agentic registration. There is no `agent_auth` block in the authorization server metadata, no identity endpoint, no claim endpoint, no anonymous or `service_auth` registration, and no ID-JAG or other identity-assertion grant. A human with a RightMessage account always authorizes access, either by approving an OAuth consent screen or by creating a token.

## Step 1 — Discover

An unauthenticated MCP request (send `Accept: application/json, text/event-stream`) returns:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="mcp", resource_metadata="https://api.rightmessage.com/.well-known/oauth-protected-resource/mcp/rightmessage"
```

Fetch the `resource_metadata` URL (RFC 9728 Protected Resource Metadata):

```json
{
  "resource": "https://api.rightmessage.com/mcp/rightmessage",
  "authorization_servers": ["https://api.rightmessage.com"],
  "scopes_supported": ["mcp:use"]
}
```

Then fetch the authorization server metadata (RFC 8414) at `https://api.rightmessage.com/.well-known/oauth-authorization-server`:

```json
{
  "issuer": "https://api.rightmessage.com",
  "authorization_endpoint": "https://api.rightmessage.com/oauth/authorize",
  "token_endpoint": "https://api.rightmessage.com/oauth/token",
  "registration_endpoint": "https://api.rightmessage.com/oauth/register",
  "response_types_supported": ["code"],
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["mcp:use"],
  "grant_types_supported": ["authorization_code", "refresh_token"]
}
```

A REST API request without a valid token returns `401` with `WWW-Authenticate: Bearer realm="rightmessage-api"` and no `resource_metadata`, because the REST API has no OAuth flow. Go straight to the personal API token method.

## Step 2 — Pick a method

1. **Calling the MCP server from an MCP client that supports OAuth** → [Hosted OAuth](#hosted-oauth-mcp-only).
2. **Calling the REST API, or an MCP client without OAuth support** → [Personal API token](#personal-api-token).

There is no method that works without a human account holder.

## Step 3 — Register

### Hosted OAuth (MCP only)

Register a public client with OAuth 2.0 Dynamic Client Registration (RFC 7591):

```http
POST https://api.rightmessage.com/oauth/register
Content-Type: application/json

{ "client_name": "Your agent", "redirect_uris": ["https://your-client.example/callback"] }
```

The response contains a `client_id`, your `redirect_uris`, `grant_types`, and `token_endpoint_auth_method: "none"`. There is no client secret.

Redirect URIs are restricted. HTTP(S) callbacks must start with an allowed origin — including `https://claude.ai`, `https://chatgpt.com`, `https://cursor.com`, `https://vscode.dev`, `http://localhost`, and `http://127.0.0.1` — and the `cursor` and `vscode` private-use schemes are accepted. Anything else fails with `400 invalid_redirect_uri`.

### Personal API token

The account holder creates it; you cannot. Ask the user to open Your account › API & AI access › API tokens in the RightMessage app, create a named token, and hand you the value (it is shown once). Creating tokens requires a project on the Scale or Pro plan. Tokens created in the app get every ability. A token holder can mint narrower tokens with `POST https://api.rightmessage.com/v1/tokens` and an `abilities` array:

- `read` — Configuration, analytics, data, and export status GET routes.
- `write` — Everything read can do, plus creating, updating, and deleting configuration and starting exports.
- `publish` — Publishing the project draft. It doesn't grant the read or write routes by itself.
- `*` — Every ability. Tokens created in the app, or without abilities, get this by default.

## Step 4 — Claim

There is no claim ceremony. For OAuth, the human step is the consent screen: send the user to `https://api.rightmessage.com/oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `scope=mcp:use`, `state`, `code_challenge`, and `code_challenge_method=S256`. They sign in to RightMessage and approve your client. For API tokens, the human step is creating the token.

## Step 5 — Exchange

Exchange the authorization code at the token endpoint with your PKCE verifier:

```http
POST https://api.rightmessage.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=…&redirect_uri=…&code=…&code_verifier=…
```

Access tokens last 60 minutes. Use `grant_type=refresh_token` to renew; refresh tokens last one year. Personal API tokens need no exchange and do not expire until revoked.

## Step 6 — Use the access_token

Send the credential as a bearer token:

```http
Authorization: Bearer <token>
```

- MCP: `POST https://api.rightmessage.com/mcp/rightmessage` with an OAuth access token or a personal API token.
- REST: `https://api.rightmessage.com/v1/{projectId}/...` with a personal API token. The OpenAPI description is at `https://api.rightmessage.com/openapi.json`.

Rate limits:

- Token and OAuth connection management (/tokens, /oauth-connections): 60 requests per minute
- Project routes (/{projectId}/...): 120 requests per minute
- MCP endpoint: 120 requests per minute

## Errors

Errors are JSON.

| Status | Body | Meaning |
| --- | --- | --- |
| 400 | `{"error": "invalid_redirect_uri" \| "invalid_client_metadata", "error_description": "…"}` | Dynamic client registration rejected. |
| 400/401 | `{"error": "invalid_grant", "error_description": "…", …}` | Token endpoint rejected the code, verifier, or refresh token (RFC 6749 shape). |
| 401 | `{"message": "Unauthenticated."}` | Missing, expired, or revoked token. On the REST API, also returned for OAuth access tokens. |
| 403 | `{"message": "…"}` | The token lacks the needed ability or `mcp:use` scope, the plan doesn't include API access, the user has no eligible project, or the account is suspended (`"code": "account_suspended"`). |
| 422 | `{"message": "…", "errors": {"field": ["…"]}}` | Validation failed. |
| 429 | `{"message": "Too Many Attempts."}` | Rate limited; honour `Retry-After`. |

## Revocation

There is no RFC 7009 revocation endpoint. Credentials are revoked by the account holder or with a personal API token:

- Personal API tokens: Your account › API & AI access › API tokens → Revoke, or `DELETE https://api.rightmessage.com/v1/tokens/{id}` (returns `204`).
- OAuth connections: Your account › API & AI access → AI assistants → Disconnect, or `DELETE https://api.rightmessage.com/v1/oauth-connections/{clientId}`.

After revocation, requests fail with `401`. Stop and ask the user to reconnect.

More: [MCP setup](https://rightmessage.com/mcp) · [Developers](https://rightmessage.com/developers) · [API tokens and permissions](https://rightmessage.com/help/api-tokens-and-permissions)