OAuth reference

How Datasense authorizes OAuth requests, which permissions and data are shared, and how to implement an MCP OAuth client.

Setting up a connection? Start with Get started.

How OAuth requests are authorized

You approve a connection. Sign in, select websites and permissions. Datasense saves that approval for you and the client.
The client receives a token. It identifies that connection. It doesn't contain your session or your website keys.
Every request is checked. The token's expiry, the MCP endpoint it was issued for, that the connection is active, the permission the tool needs, and that you still own the website.

Revoke a connection in API & MCP → Connected apps. Its next request and refresh are rejected.

Permissions

Scope	Access
`account:read`	Read your name, email and plan.
`websites:read`	List the selected websites with their names and domains.
`settings:read`	Read website settings: timezone, tracking mode and session replay.
`analytics:read`	Read traffic, sources, goals, revenue, JavaScript errors and bot traffic.
`visitors:read`	Read visitor journeys, with names, emails and traits removed. Also needs analytics:read.
`visitors:details`	Include the names, emails and traits your site sent with identify. Also needs visitors:read.

Visitor tools need analytics:read and visitors:read. Without visitors:details they return pseudonymous visitor IDs and generated names, and leave out names, emails and traits your site sent with identify. Paths and goal names can still contain personal data if your site put it there.

OAuth client implementation

Item	Value
Issuer	`https://usedatasense.com`
Authorization server metadata	`https://usedatasense.com/.well-known/oauth-authorization-server`
Protected resource metadata	`https://usedatasense.com/.well-known/oauth-protected-resource/api/mcp`
Authorization endpoint	`https://usedatasense.com/oauth/authorize`
Token endpoint	`https://usedatasense.com/oauth/token`
Client registration	`https://usedatasense.com/oauth/register`
Revocation endpoint	`https://usedatasense.com/oauth/revoke`
MCP resource	`https://usedatasense.com/api/mcp`
Grants	Authorization code with PKCE S256; rotating refresh tokens
Access token lifetime	1 hour
Refresh token lifetime	Up to 30 days
Connection lifetime	90 days from consent; reconnect afterwards

Unauthenticated MCP requests get 401 with WWW-Authenticate: Bearer resource_metadata="…", so clients can discover the authorization server.
Use the exact MCP URL as resource. Tokens only work at that endpoint.
Token requests are application/x-www-form-urlencoded. Send tokens only in Authorization: Bearer ….
The authorization response includes iss and echoes state.
Public clients use none with PKCE; confidential clients use client_secret_basic or client_secret_post as well as PKCE. Implicit, password and plain PKCE aren't supported.
Client ID metadata documents: an HTTPS client_id URL is fetched (no redirects, no private networks, 64 KB at most) and its redirect_uris used.
Dynamic registration: HTTPS, loopback HTTP and app-specific scheme redirect URIs. A loopback redirect may use any port. Registrations expire after a year.
Codes, tokens and client secrets are stored as hashes. Codes expire after 2 minutes and work once. Reusing a code or a rotated refresh token revokes the connection.
The consent page expires after 10 minutes and is bound to the signed-in account.

Tool permissions

Tool	Required scopes
`datasense_account_get`	`account:read`
`datasense_websites_list`	`websites:read`
`datasense_websites_get`	`settings:read`
`datasense_analytics_metadata`	`analytics:read`
`datasense_analytics_overview`	`analytics:read`
`datasense_analytics_timeseries`	`analytics:read`
`datasense_analytics_realtime`	`analytics:read`
`datasense_analytics_realtime_map`	`analytics:read`
`datasense_analytics_pages`	`analytics:read`
`datasense_analytics_referrers`	`analytics:read`
`datasense_analytics_campaigns`	`analytics:read`
`datasense_analytics_countries`	`analytics:read`
`datasense_analytics_regions`	`analytics:read`
`datasense_analytics_cities`	`analytics:read`
`datasense_analytics_browsers`	`analytics:read`
`datasense_analytics_operating_systems`	`analytics:read`
`datasense_analytics_devices`	`analytics:read`
`datasense_analytics_goals_breakdown`	`analytics:read`
`datasense_errors_list`	`analytics:read`
`datasense_bot_traffic_summary`	`analytics:read`
`datasense_bot_traffic_pages`	`analytics:read`
`datasense_visitors_search`	`analytics:read` + `visitors:read`
`datasense_visitors_get`	`analytics:read` + `visitors:read`

Read this page as markdown llms.txt