Scopes & Permissions

OAuth scopes provide granular control over what your application can access. Each scope grants specific permissions and access to certain API endpoints. Request only the scopes you need to follow the principle of least privilege.

Quick Reference

All available scopes organized by category. Click any scope to jump to detailed information.

Understanding Scopes

Scopes are permissions that you request when authenticating with TinyRebrand's API. Users will see exactly what permissions your application is requesting, and they can grant or deny access. Each scope follows the format resource:action.

Available Scopes

user:read

Read user profile information

Permissions:

• View user profile
• Access user preferences
• Read account status

Endpoints:

• GET /user/me
• GET /user/preferences

user:write

Modify user profile and settings

Permissions:

• Update user profile
• Change user preferences
• Manage account settings

Endpoints:

• PUT /user/me
• PATCH /user/preferences

links:read

Read link data and analytics

Permissions:

• View all user links
• Access link details
• Read link metadata

Endpoints:

• GET /user/link
• GET /user/link/:id

links:write

Create, update, and delete links

Permissions:

• Create new links
• Update existing links
• Delete links
• Manage link settings

Endpoints:

• POST /user/link
• PUT /user/link/:id
• DELETE /user/link/:id

domains:read

View custom domains

Permissions:

• List user domains
• View domain details
• Check domain status

Endpoints:

• GET /user/domain
• GET /user/domain/:id

domains:write

Manage custom domains

Permissions:

• Add custom domains
• Update domain settings
• Delete domains

Endpoints:

• POST /user/domain
• PUT /user/domain/:id
• DELETE /user/domain/:id

stats:read

Access analytics and statistics

Permissions:

• View click analytics
• Access traffic data
• Read performance metrics

Endpoints:

• GET /user/stats
• GET /user/link/:id/stats

tags:read

View link tags and categories

Permissions:

• List all tags
• View tag details
• Access tag analytics

Endpoints:

• GET /user/tags
• GET /user/tags/:id

tags:write

Create and manage tags

Permissions:

• Create new tags
• Update tag names
• Delete tags
• Assign tags to links

Endpoints:

• POST /user/tags
• PUT /user/tags/:id
• DELETE /user/tags/:id

subscription:read

View subscription and billing information

Permissions:

• View subscription status
• Access billing history
• Read usage limits

Endpoints:

• GET /user/subscription
• GET /user/billing

tokens:read

View OAuth clients and personal access tokens

Permissions:

• List OAuth clients
• View OAuth client details
• List personal access tokens
• View token details

Endpoints:

• GET /user/oauth-clients
• GET /user/oauth-clients/:id
• GET /user/tokens
• GET /user/tokens/:id

tokens:write

Create and manage authentication tokens

Permissions:

• Create OAuth clients
• Update OAuth clients
• Regenerate client secrets
• Create personal access tokens
• Update token details

Endpoints:

• POST /user/oauth-clients
• PUT /user/oauth-clients/:id
• POST /user/oauth-clients/:id/regenerate-secret
• POST /user/tokens

tokens:delete

Revoke tokens and delete OAuth clients

Permissions:

• Delete OAuth clients
• Revoke personal access tokens
• Deactivate authentication methods

Endpoints:

• DELETE /user/oauth-clients/:id
• DELETE /user/tokens/:id

Scope Combinations

You can request multiple scopes in a single authorization request. Here are some common combinations:

Read-Only Analytics Dashboard

Perfect for analytics dashboards that need to display user information, links, and statistics.

Scopes: user:read, links:read, stats:read

Link Management Application

Ideal for applications that create and manage links with tagging capabilities.

Scopes: user:read, links:read, links:write, tags:read, tags:write

Full Access Integration

Complete access for comprehensive integrations (excluding billing information).

Scopes: user:read, user:write, links:read, links:write, domains:read, domains:write, stats:read, tags:read, tags:write

Developer Tools Integration

For developer tools that need to manage authentication and access user data.

Scopes: user:read, tokens:read, tokens:write, tokens:delete

Requesting Scopes

Include the desired scopes in your authorization request:

# Authorization Code Flow
GET /oauth/authorize?response_type=code&client_id=YOUR_CLIENT_ID&scope=user:read%20links:read%20stats:read

# Password Grant Flow
POST /oauth/token
{
"grant_type": "password",
"client_id": "web-client",
"username": "[email protected]",
"password": "password",
"scope": "user:read links:read stats:read"
}

Scope Validation

When making API calls, the system validates that your access token has the required scope. If you attempt to access an endpoint without the proper scope, you'll receive a 403 Forbidden error.

Best Practices

• Request minimal scopes: Only request the permissions you actually need
• Explain permissions: Clearly communicate to users why you need specific scopes
• Handle rejections gracefully: Users may deny some requested scopes
• Separate read/write: Consider requesting read access first, then write access when needed