OAuth Authentication

The Qwairy MCP server uses OAuth 2.1 with PKCE for secure authentication. Your credentials are never shared with AI clients: only a secure, scoped access token.

How it works

Most MCP clients handle this flow automatically. You just click “Authorize” when prompted: there’s no team to pick and no manual token management. The connection is user-scoped: it can read every MCP-eligible workspace you can access directly or through inherited parent-team access.

OAuth endpoints

Endpoint	URL
Discovery	`https://mcp.qwairy.co/.well-known/oauth-authorization-server`
Dynamic client registration	`https://auth.qwairy.co/register`
Authorization	`https://auth.qwairy.co/authorize`
Token	`https://auth.qwairy.co/token`
Revocation	`https://auth.qwairy.co/revoke`

Modern MCP clients automatically discover these endpoints from the server URL. You only need to provide https://mcp.qwairy.co: the client fetches the OAuth configuration via the discovery endpoint.

Available scopes

Request only the scopes you need:

Scope	Description
`read:brands`	See the list of brands monitored on this account (brand names and primary domains).
`read:visibility`	See visibility metrics, GEO scores, and trends for monitored brands across AI providers.
`read:competitors`	See competitors detected in AI answers, their rankings, sentiment, and evolution over time.
`read:sources`	See the third-party domains and URLs that AI providers cite as sources in answers.
`read:prompts`	See the questions and prompts monitored across AI providers, including their text, status, and tags. `get_prompt_answers` includes response excerpts limited to the first 500 characters.
`read:answers`	See the full text and metadata of AI answers collected for monitored prompts (response text, provider, citations, sentiment).
`read:topics`	See topic groups, keyword performance, and topic-level breakdowns of brand visibility.
`read:pitch-audits`	List and read completed or in-progress Pitch Audit reports for agency workspaces you can access.
`read:measure`	See off-AI analytics from connected integrations: search performance, AI-referral traffic, configured conversions and value, and retained AI crawler rollups.

If no scopes are specified, all read scopes are granted by default. If any requested scope is unrecognized, the entire authorization request is rejected with invalid_scope.

read:measure and read:pitch-audits are newer scopes. Existing OAuth connections must reconnect and re-authorize to gain access to their tools. Scopes are never expanded silently on an already-issued token.

Token lifecycle

The OAuth flow issues a single user-scoped access token: the same kind of token as a Personal Access Token (qw-usr-). It is long-lived and has no refresh token: there is nothing to rotate, and clients simply reuse the bearer until it is revoked.

Token	Duration	Notes
Current OAuth or PAT access token (`qw-usr-`)	No fixed expiry	Revoke any time from Team Management > MCP Server; re-authorize to get a new one
Legacy OAuth access token (`qw-mcp-`)	1 hour	Already-issued legacy connections only
Legacy rotating refresh token (`qw-mcpr-`)	30 days	Already-issued legacy connections only; each refresh rotates the token
Authorization Code	5 minutes	One-time use, PKCE-protected

New OAuth connections issue a long-lived qw-usr- token without a refresh token. Disconnecting and reconnecting a legacy connection migrates it to this current token flow.

Personal Access Tokens

For headless clients that cannot run an interactive OAuth flow: automation platforms (n8n, Make), scripts, or custom agents: Qwairy supports user-scoped Personal Access Tokens (PATs). Create and revoke them from Team Management > MCP Server in Qwairy.

A PAT is prefixed qw-usr- and is tied to your user account, not a single team.
It can read every MCP-eligible team you can access directly or through inherited parent-team access, so one token can cover multiple workspaces.
Pass it as a bearer token: Authorization: Bearer qw-usr-....
Like the OAuth access token, a PAT has no fixed expiry. Revoke it from Team Management > MCP Server when it is no longer needed.

PATs are read-only, like all Qwairy MCP access: they never expose write operations.

Choosing a team

Brand-scoped tools take a brandId, and Qwairy resolves that brand to exactly one owning team for the call. A response never aggregates brand data across teams. Call list_brands first, then pass the brandId you want. User-scoped tokens can include directly accessible teams and sub-teams inherited through a parent-team Owner or Manager role. list_pitch_audits is the other cross-workspace discovery tool: it lists only agency workspaces the token may access and accepts an optional teamId filter. Detail calls still resolve one audit from one authorized workspace.

PKCE support

The server requires PKCE with the S256 method only:

S256: SHA-256 hash of the code verifier

The plain method is not supported. Most MCP clients use S256 by default, so no extra configuration is needed.

Security features

Scoped Access

Tokens are scoped to specific data types. An MCP client can only access what you’ve authorized.

Team Isolation

Both OAuth connections and Personal Access Tokens are user-scoped (qw-usr-): they span MCP-eligible teams you can access directly or through inherited parent Owner or Manager access. Each brand-scoped call still resolves the requested brandId to exactly one owning team, so one response never mixes brand data across teams.

Short-Lived Authorization Code

The authorization code is single-use and expires after 5 minutes, so the window to exchange it for a token is tight. The issued access token itself is revocable at any time (see below).

Revocation

You can revoke access at any time from your Qwairy account settings.

Manual token exchange

For developers building custom MCP clients, register the public client first and reuse the returned client_id throughout the authorization-code exchange.

1. Register the client

The redirect URI registered here must match the redirect URI used in both later requests.

curl --request POST https://auth.qwairy.co/register \
  --header 'Content-Type: application/json' \
  --data '{
    "client_name": "My Qwairy MCP client",
    "redirect_uris": ["http://127.0.0.1:8765/callback"],
    "grant_types": ["authorization_code"],
    "response_types": ["code"]
  }'

The response includes the registered public client ID:

{
  "client_id": "mcp-client-0123456789abcdef0123456789abcdef",
  "client_name": "My Qwairy MCP client",
  "redirect_uris": ["http://127.0.0.1:8765/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

2. Start authorization

Generate an RFC 7636 verifier and its S256 challenge, then open this URL in the user’s browser. Replace REGISTERED_CLIENT_ID with the client_id returned above.

GET https://auth.qwairy.co/authorize
  ?response_type=code
  &client_id=REGISTERED_CLIENT_ID
  &redirect_uri=http%3A%2F%2F127.0.0.1%3A8765%2Fcallback
  &scope=read%3Abrands%20read%3Avisibility
  &state=RANDOM_STATE
  &code_challenge=BASE64URL_SHA256_OF_VERIFIER
  &code_challenge_method=S256

The callback contains code and state. Verify state before exchanging the code.

3. Exchange the code

curl --request POST https://auth.qwairy.co/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=AUTH_CODE_FROM_CALLBACK' \
  --data-urlencode 'client_id=REGISTERED_CLIENT_ID' \
  --data-urlencode 'redirect_uri=http://127.0.0.1:8765/callback' \
  --data-urlencode 'code_verifier=ORIGINAL_CODE_VERIFIER'

Response:

{
  "access_token": "qw-usr-abc123...",
  "token_type": "Bearer",
  "scope": "read:brands read:visibility"
}

The access token is a long-lived, user-scoped token (qw-usr-). There is no refresh_token or expires_in: reuse the bearer until you revoke it.

4. Reuse or revoke

The token does not expire and has no refresh step: reuse the bearer for subsequent requests. To rotate it, revoke the old one and run the authorization flow again:

POST https://auth.qwairy.co/revoke
Content-Type: application/x-www-form-urlencoded

token=qw-usr-abc123...

Troubleshooting

”Invalid or expired token”

The token was revoked: user-scoped tokens do not expire on their own. Disconnect and reconnect to authorize a new one.

”Insufficient scope”

The tool you’re trying to use requires a scope that wasn’t granted. Reconnect and authorize all requested scopes.

”No eligible team”

Your account isn’t a member of any team on an MCP-eligible plan (Starter and above), or the subscription has lapsed. Authorization is denied until at least one workspace is eligible.

Get started

Tool reference

Examples

Workflows

How it works

OAuth endpoints

Available scopes

Token lifecycle

Personal Access Tokens

Choosing a team

PKCE support

Security features

Manual token exchange

1. Register the client

2. Start authorization

3. Exchange the code

4. Reuse or revoke

Troubleshooting

”Invalid or expired token”

”Insufficient scope”

”No eligible team”

​How it works

​OAuth endpoints

​Available scopes

​Token lifecycle

​Personal Access Tokens

​Choosing a team

​PKCE support

​Security features

​Manual token exchange

​1. Register the client

​2. Start authorization

​3. Exchange the code

​4. Reuse or revoke

​Troubleshooting

​”Invalid or expired token”

​”Insufficient scope”

​”No eligible team”

How it works

OAuth endpoints

Available scopes

Token lifecycle

Personal Access Tokens

Choosing a team

PKCE support

Security features

Manual token exchange

1. Register the client

2. Start authorization

3. Exchange the code

4. Reuse or revoke

Troubleshooting

”Invalid or expired token”

”Insufficient scope”

”No eligible team”