# Create, restrict, and revoke API tokens

Create a token, choose REST API abilities through the API, and revoke credentials you no longer use.

Available on the Scale and Pro plans.

Create an API token when your application needs to read or change RightMessage projects without a browser session.

## Before you start

Sign in with the account whose projects the application should access. Token creation requires API access on the selected project. The token belongs to your user account, not just the project currently open.

You also need secure server-side storage for the token. Tokens created in the app have full access by default.

For an AI assistant that supports hosted OAuth, use [Connect RightMessage to your AI assistant](https://rightmessage.com/help/connect-rightmessage-to-ai-assistants-via-mcp) instead. You won't need to copy a token.

## Create a token in the app

1. Open the user menu and choose **Your profile**.
2. Open **API Tokens**.
3. Under **Create API Token**, enter a **Token Name**, such as `WorkForge reporting`.
4. Click **Create**.
5. Use **Copy token** to save the new value in your application's secret storage.

![API token creation form with an example integration name before creating the first token](https://rightmessage.com/help/screens/profile-api-tokens.light.webp)

RightMessage shows the complete token once. After that, the list shows its **Name**, **Created** date, and **Last Used** date. **Never** means no use has been recorded.

The dashboard has no ability selector. Tokens created here have `*`, which means full access. To choose narrower REST permissions, [create a token through the API](#create-a-token-with-narrower-rest-abilities). Keep tokens out of browser JavaScript, public repositories, screenshots, and shared AI conversations.

## Create a token with narrower REST abilities

The token creation API accepts an `abilities` array. Use this when an application needs fewer project operations than the dashboard's default token permits.

1. Choose the abilities your application needs.
2. Create the token with `POST https://api.rightmessage.com/v1/tokens`.
3. Store the returned `data.plainTextToken` securely.
4. Configure the application to send that value in its `Authorization: Bearer` header.

| Ability   | Project REST operations                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------------------- |
| `read`    | Read endpoints. Does not permit project mutations or publishing.                                            |
| `write`   | Read endpoints and write endpoints, including starting exports. Does not include publishing.                |
| `publish` | Publish the project's draft configuration. Add `read` if the application also needs to inspect the project. |
| `*`       | All abilities. This is the default when `abilities` is omitted.                                             |

This illustrative request creates a reporting token. `RIGHTMESSAGE_TOKEN` is an existing credential stored in your environment.

```bash
curl --request POST 'https://api.rightmessage.com/v1/tokens' \
	--header "Authorization: Bearer $RIGHTMESSAGE_TOKEN" \
	--header 'Accept: application/json' \
	--header 'Content-Type: application/json' \
	--data '{"name":"WorkForge reporting","abilities":["read"]}'
```

The response is HTTP `201`. The `data` object contains `id`, `name`, `abilities`, and the one-time `plainTextToken`. See [Tokens and OAuth connections API reference](https://rightmessage.com/help/rest-api-access) for the complete contract.

> **What abilities do not restrict**
>
> These abilities control project REST `/v1` routes. They are not a complete credential sandbox. User-level token management, dashboard `/api` routes, and MCP authorization do not use those project REST ability checks. Dashboard routes still apply their own project and operation permissions. Don't give a token to an untrusted application on the assumption that `read` makes every possible use read-only.

There is no token-edit endpoint or dashboard ability editor. To change a token's abilities, create a replacement and revoke the old token. Selecting an active project in MCP is also not a credential restriction.

## Revoke a token

Deleting a token immediately stops applications that use it from authenticating.

1. Open **Your profile**.
2. Open **API Tokens**.
3. Find the token by its **Name**.
4. Click **Delete** on that row.
5. Review the **Delete API Token** dialog.
6. Click **Delete Token**.

The token disappears from the list. Use **Cancel** if you're not ready to interrupt the application.

If a token is exposed, revoke it rather than renaming the application. Create a replacement only for the applications that still need access.

## Make authenticated requests

Use the [REST API authentication and request conventions](https://rightmessage.com/help/rest-api-overview) for request headers, project IDs, and error handling. OAuth connections are revoked separately under [AI Connections](https://rightmessage.com/help/mcp-authorization-reference).