Most MCP clients (Claude Code, Cursor, VS Code, Windsurf, Codex CLI, OpenCode, Claude Desktop) use API key authentication instead. OAuth is only needed for clients that initiate auth through a browser login flow.
How it works
OAuth 2.1 Authorization Code with PKCE follows this sequence:Discovery
Xquik publishes standard OAuth discovery documents so MCP clients can auto-configure endpoints.Authorization server metadata
Response
Protected resource metadata
Response
Complete flow
Register a client
Register your MCP client to get a Redirect URI requirements:
client_id. This is a one-time setup.Response
- Production: HTTPS only
- Development:
http://localhostandhttp://127.0.0.1are allowed - Exact match required. No wildcards or subpath matching
- Public (
token_endpoint_auth_method: "none"): Default. No client secret. Used by browser apps and MCP clients. - Confidential (
token_endpoint_auth_method: "client_secret_post"): Returns aclient_secretin the registration response. Used by server-side apps.
Generate PKCE parameters
Generate a cryptographically random
code_verifier and derive the code_challenge from it.Redirect to authorization
Redirect the user to the Xquik authorization endpoint with the required query parameters.Required parameters:
Optional parameters:
The user sees a login page (Google OAuth or email magic link) followed by a consent screen. After approval, Xquik redirects back to your
| Parameter | Value |
|---|---|
response_type | code |
client_id | UUID from client registration |
redirect_uri | Must match a registered URI exactly |
code_challenge | Base64url-encoded SHA256 digest of the code_verifier |
code_challenge_method | S256 |
| Parameter | Default | Description |
|---|---|---|
scope | mcp:tools | Only mcp:tools is supported |
state | Opaque value for CSRF protection | |
resource | https://xquik.com/mcp | Target resource identifier |
The
scope and resource parameters default to the only supported values (mcp:tools and https://xquik.com/mcp). You can omit them.redirect_uri.Receive the authorization code
After the user approves, Xquik redirects to your Verify the
redirect_uri with a code parameter:state parameter matches the value you sent in step 3 to prevent CSRF attacks. The authorization code expires in 60 seconds and is single-use.Exchange code for tokens
Exchange the authorization code and your
code_verifier for an access token and refresh token.Response
Token lifetimes
| Token | Lifetime | Notes |
|---|---|---|
| Access token | 24 hours | Use the refresh token to get a new one |
| Refresh token | 30 days | Single-use. Each refresh issues a new pair |
| Authorization code | 60 seconds | Single-use. Exchange immediately |
Refresh tokens
Access tokens expire after 24 hours. Use the refresh token to get a new access token without requiring the user to log in again.Response
Token revocation
Revoke an access or refresh token when a user disconnects or your application no longer needs access.| Parameter | Required | Description |
|---|---|---|
token | Yes | The token to revoke |
client_id | Yes | The client ID that owns the token |
token_type_hint | No | access_token or refresh_token. Helps the server locate the token faster |
200 with an empty body on success. If the token is already revoked or invalid, the server still returns 200 (per RFC 7009).
Revocation errors:
| Status | Error | When |
|---|---|---|
| 400 | invalid_request | token parameter is empty or missing |
| 400 | invalid_request | client_id parameter is empty or missing |
| 401 | invalid_client | client_id does not match a registered client |
Scopes
| Scope | Description |
|---|---|
mcp:tools | Full access to all MCP tools (search tweets, manage monitors, run extractions, run draws, etc.) |
mcp:tools is supported. No partial scopes or scope combinations are available.
Client registration
Request
| Field | Type | Required | Description |
|---|---|---|---|
client_name | string | Yes | Display name shown on the consent screen |
redirect_uris | string[] | Yes | Allowed redirect URIs (1 or more) |
token_endpoint_auth_method | string | No | none (default) or client_secret_post |
grant_types | string[] | No | Defaults to ["authorization_code", "refresh_token"] |
Response
| Field | Type | Description |
|---|---|---|
client_id | string | UUID. Use this in all subsequent OAuth requests |
client_name | string | Echoed from request |
redirect_uris | string[] | Echoed from request |
grant_types | string[] | Resolved grant types |
token_endpoint_auth_method | string | Resolved auth method |
client_secret | string | Only present for confidential clients (client_secret_post) |
client_id_issued_at | number | Unix timestamp when the client ID was issued |
client_secret_expires_at | number | Always 0 (non-expiring). Only present for confidential clients |
Error responses
All errors follow the standard OAuth 2.0 error format:Authorization errors
| Error | When |
|---|---|
unsupported_response_type | response_type is not code |
invalid_request | Missing client_id, code_challenge, unknown client_id, or mismatched redirect_uri |
invalid_scope | Scope is not mcp:tools |
invalid_target | Resource is not https://xquik.com/mcp |
access_denied | User denied the authorization request |
Token errors
| Error | When |
|---|---|
invalid_request | Missing code, code_verifier, client_id, or refresh_token |
invalid_grant | Code/token is invalid, expired, or already used. Also: client_id mismatch, redirect_uri mismatch, or PKCE verification failed |
unsupported_grant_type | Grant type is not authorization_code or refresh_token |
invalid_target | Resource is not https://xquik.com/mcp |
Registration errors
| Error | Description | When |
|---|---|---|
Invalid request body | — | Request body is not valid JSON or not an object |
client_name is required | — | Missing or empty client_name |
invalid_client_metadata | client_name exceeds maximum length | client_name exceeds 256 characters |
redirect_uris must be a non-empty array of strings | — | Missing, empty, or malformed redirect_uris |
invalid_client_metadata | Too many redirect URIs | Exceeds the 10 redirect URI limit |
Invalid redirect URI: {uri}. Must be HTTPS or localhost. | — | URI is not HTTPS or localhost |
Invalid token_endpoint_auth_method. Must be one of: none, client_secret_post | — | Value is not none or client_secret_post |
grant_types must be an array of strings | — | Malformed grant_types |
invalid_client_metadata | Unsupported grant type | Grant type is not authorization_code or refresh_token |
Full example
A complete Node.js implementation of the OAuth 2.1 flow:Node.js
Where to go next
MCP Server
Connect AI agents to Xquik via MCP.
MCP Tools Reference
All MCP tools with input/output schemas.
API Key Auth
API key authentication for REST API and MCP.
Quickstart
Get your API key and make your first request.