Tiny Rebrand DocsHome

Scopes & Permissions

Fine-grained access control for TinyRebrand's OAuth 2.0 API

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.
CategoryScopes
User Management
user:readuser:write
Link Management
links:readlinks:write
Domain Management
domains:readdomains:write
Analytics & Reporting
stats:read
Organization & Tags
tags:readtags:write
Billing & Subscription
subscription:read

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

API Endpoints

GET /user/me
GET /user/preferences
user:write
Modify user profile and settings

Permissions

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

API 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

API 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

API 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

API Endpoints

GET /user/domain
GET /user/domain/:id
domains:write
Manage custom domains

Permissions

  • Add custom domains
  • Update domain settings
  • Delete domains

API 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

API 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

API 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

API 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

API Endpoints

GET /user/subscription
GET /user/billing

Scope Combinations

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

Read-Only Analytics Dashboard

user:read links:read stats:read

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

Link Management Application

user:read links:read links:write tags:read tags:write

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

Full Access Integration

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

Complete access for comprehensive integrations (excluding billing information).

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

Previous

Quick Start

Next

Rate Limits