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
Category | Scopes |
---|---|
User Management | |
Link Management | |
Domain Management | |
Analytics & Reporting | |
Organization & Tags | |
Billing & Subscription |
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
Permissions
- View user profile
- Access user preferences
- Read account status
API Endpoints
user:write
Permissions
- Update user profile
- Change user preferences
- Manage account settings
API Endpoints
links:read
Permissions
- View all user links
- Access link details
- Read link metadata
API Endpoints
links:write
Permissions
- Create new links
- Update existing links
- Delete links
- Manage link settings
API Endpoints
domains:read
Permissions
- List user domains
- View domain details
- Check domain status
API Endpoints
domains:write
Permissions
- Add custom domains
- Update domain settings
- Delete domains
API Endpoints
stats:read
Permissions
- View click analytics
- Access traffic data
- Read performance metrics
API Endpoints
subscription:read
Permissions
- View subscription status
- Access billing history
- Read usage limits
API Endpoints
Scope Combinations
Read-Only Analytics Dashboard
Perfect for analytics dashboards that need to display user information, links, and statistics.
Link Management Application
Ideal for applications that create and manage links with tagging capabilities.
Full Access Integration
Complete access for comprehensive integrations (excluding billing information).
Requesting Scopes
# 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.
- • Scopes cannot be modified after token issuance
- • Request minimal scopes necessary for your application
- • Some scopes may require additional verification
- • Scope names are case-sensitive
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