Authentication and scopes
Choose between website keys and account tokens, then grant the smallest access needed.
Token types
| Token | Name | Scope | Best for |
|---|---|---|---|
ds_sk_ |
Website key | One website, every permission | Server-side payments, reading one website |
ds_at_ |
Account token | Your websites (all, or specific ones), the permissions you pick | AI agents, MCP clients that need a token, scripts across websites |
ds_oat_ |
OAuth token | The websites and permissions approved for one app | Issued to MCP clients when you sign in; MCP only |
Website keys (ds_sk_)
Create one in a website's Settings → API or Settings → Revenue. Each website has one key; regenerating it replaces the old one. The website is implied:
sh
curl "https://usedatasense.com/api/v1/analytics/overview" \
-H "Authorization: Bearer ds_sk_xxx"Account tokens (ds_at_)
Create them in API & MCP. Limit them by:
- Permissions, such as
analytics:readorpayments:write. - Websites: all your websites (including ones you add later), or a fixed list.
Pass websiteId to say which website to query. It can be left out when the token reaches exactly one website.
sh
curl "https://usedatasense.com/api/v1/analytics/overview?websiteId=YOUR_SITE_ID" \
-H "Authorization: Bearer ds_at_xxx"Permissions
| Permission | Allows | OAuth |
|---|---|---|
account:read |
Read your name, email and plan. | Yes |
websites:read |
List the selected websites with their names and domains. | Yes |
settings:read |
Read website settings: timezone, tracking mode and session replay. | Yes |
analytics:read |
Read traffic, sources, goals, revenue, JavaScript errors and bot traffic. | Yes |
visitors:read |
Read visitor journeys, with names, emails and traits removed. Also needs analytics:read. | Yes |
visitors:details |
Include the names, emails and traits your site sent with identify. Also needs visitors:read. | Yes |
payments:write |
Record or delete payments through the REST API. | No |
For AI agents
An agent that reads analytics needs websites:read,analytics:read. Add visitors:read for visitor journeys, and visitors:details only if it should see names and emails. Prefer OAuth sign-in for MCP clients that support it: no token to copy, and you can revoke it per app.