OAuth Scopes
Scopes define what actions an application can perform on behalf of a user. When authorizing an app, users see exactly which permissions the app is requesting.
Principle of Least PrivilegeRequest only the scopes your application actually needs. Users are more likely to approve apps that request minimal permissions.
Short URL Scopes
| Scope | Permission | Description |
|---|
shorturl:read | Read URLs | List and view short URL details and metadata |
shorturl:create | Create URLs | Shorten long URLs, set custom aliases |
shorturl:update | Edit URLs | Modify destination URLs and settings |
shorturl:delete | Delete URLs | Permanently remove short URLs |
QR Code Scopes
| Scope | Permission | Description |
|---|
qrcode:read | Read QR Codes | List and view QR code details |
qrcode:create | Create QR Codes | Generate QR codes for URLs, text, WiFi, vCards |
qrcode:update | Edit QR Codes | Modify QR code content and design |
qrcode:delete | Delete QR Codes | Permanently remove QR codes |
Analytics Scopes
| Scope | Permission | Description |
|---|
analytics:read | View Analytics | Access click statistics, traffic data, and performance metrics |
Analytics access may require a paid plan. If a user’s plan doesn’t include analytics, requests using this scope will return a plan limitation error.
Domain Scopes
| Scope | Permission | Description |
|---|
domain:read | View Domains | List custom domains and subdomains |
domain:create | Add Domains | Register new custom domains |
Campaign Scopes
| Scope | Permission | Description |
|---|
campaign:read | View Campaigns | Access campaign data and UTM parameters |
campaign:create | Create Campaigns | Create and manage marketing campaigns |
Scope Bundles
For convenience, you can request multiple scopes at once. Here are common bundles:
Read-Only Access
shorturl:read qrcode:read analytics:read
Standard Integration
shorturl:read shorturl:create qrcode:read qrcode:create analytics:read
Full Access
shorturl:read shorturl:create shorturl:update shorturl:delete qrcode:read qrcode:create qrcode:update qrcode:delete analytics:read domain:read campaign:read campaign:create
Legacy Scope Names
For backwards compatibility, we also support legacy scope names:
| Legacy Scope | Maps To |
|---|
url:read | shorturl:read |
url:create | shorturl:create |
url:update | shorturl:update |
url:delete | shorturl:delete |
qr:read | qrcode:read |
qr:create | qrcode:create |
qr:update | qrcode:update |
qr:delete | qrcode:delete |
read | shorturl:read qrcode:read analytics:read |
write | shorturl:create qrcode:create |
We recommend using the new descriptive scope names for all new integrations. Legacy scopes are maintained for existing apps but may be deprecated in the future.
Scope Validation
When requesting scopes, the following validations apply:
1. Plan Limits
Scopes are checked against the user’s plan. If a user’s plan doesn’t include a feature:
{
"error": "invalid_scope",
"error_description": "Your plan does not include analytics access"
}
2. App Registration
Apps can only request scopes they registered for. If you request a scope not in your app’s allowed list:
{
"error": "invalid_scope",
"error_description": "Scope 'campaign:create' not allowed for this client"
}
3. User Consent
Users see all requested scopes on the authorization page and can choose to deny access if they’re uncomfortable with the permissions.
Requesting Scopes
In Authorization URL
Space-separated or plus-separated:
https://jmpy.me/mcp/oauth/authorize?
client_id=YOUR_CLIENT_ID&
scope=shorturl:read+shorturl:create+qrcode:read
In Dynamic Registration
Array format in JSON:
{
"client_name": "My App",
"redirect_uris": ["https://myapp.com/callback"],
"scope": "shorturl:read shorturl:create qrcode:read qrcode:create"
}
Scope Display in UI
When users authorize your app, they see a friendly description of each scope:
| Scope | User Sees |
|---|
shorturl:create | Create Short URLs - Shorten long URLs into tiny, memorable links with custom aliases |
qrcode:create | Generate QR Codes - Create scannable QR codes for URLs, text, WiFi, and vCards |
analytics:read | View Analytics - Access click statistics, traffic data, and performance metrics |
Pre-Registered App Scopes
Pre-registered OAuth clients (OpenAI, Claude, Zapier) have default scopes:
| App | Default Scopes |
|---|
| OpenAI/ChatGPT | shorturl:read shorturl:create qrcode:read qrcode:create analytics:read |
| Claude (MCP) | shorturl:read shorturl:create qrcode:read qrcode:create analytics:read |
| Zapier | shorturl:read shorturl:create qrcode:read qrcode:create |
Next Steps
