Documentation / Getting Started / Authentication

Authentication

Log in to OppAlerts and choose how your code or AI agent can access it.

The web app

Log in at oppalerts.com/login. The web app is at https://oppalerts.com/app/.

API tokens

  • Create a personal token on the API & MCP Tokens page, oppalerts.com/app/account/api_tokens. API & MCP Tokens explains the form, expiration date, and how to revoke a token.
  • Send the token in the header Authorization: Bearer YOUR_TOKEN.
  • Tokens are created and revoked on the website only. No MCP tool or API route can create or revoke them.

Scopes

A scope defines what a token can do. A token or an OAuth app has one or more of these:

  • api:read: read OppAlerts data through the API and the MCP tools.
  • mcp:use: use the OppAlerts MCP tools. The MCP server rejects a token without this scope.
  • api:write: edit campaigns through the API and the MCP tools. Each tool that edits a campaign rejects a token without this scope. It is new in this release.

A token or a connected app made before this release has no api:write. It can still read data as before. To edit campaigns, create a new token with the api:write box checked, or connect the app again and give it edit permissions.

The person's permissions also apply. An account or campaign viewer can read data but cannot edit it, regardless of the token's scopes. See Team.

OAuth

The MCP server and the API also accept an OAuth access token. OAuth 2.0 with PKCE is at https://auth.oppalerts.com. An AI agent such as Claude Code uses OAuth: the first call opens a browser window for the OppAlerts login.

  • The OppAlerts sign-in page lists the permissions the app requests, each with a checked box. An app that connects to the MCP server asks for edit permissions too: the list has the line "Edit campaigns through the API and the MCP server". Uncheck that box to give the app read-only access.
  • An app with read-only access can request edit permissions later. When it calls a tool that edits a campaign, the server returns HTTP 403 and identifies the missing scope, as required by the MCP standard. An app that follows the standard then opens the sign-in page again.
  • To reconnect an app, find it under Connected apps on the API & MCP Tokens page and click Disconnect. Then sign in again from the app.
  • An OAuth access token lasts 24 hours. A refresh token lasts 90 days.
  • An MCP client finds the OAuth server at https://mcp.oppalerts.com/.well-known/oauth-protected-resource/mcp.
  • An MCP client can register itself (dynamic client registration, RFC 7591).

The URLs

  • MCP server: https://mcp.oppalerts.com/mcp. The bare host https://mcp.oppalerts.com returns 404.
  • API: https://api.oppalerts.com/v1/.