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.

Category	Scopes
User Management	user:read user:write
Link Management	links:read links:write
Domain Management	domains:read domains:write
Analytics & Reporting	stats:read
Organization & Tags	tags:read tags:write
Billing & Subscription	subscription:read
Authentication & Tokens	tokens:read tokens:write tokens:delete

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

tokens:read

View OAuth clients and personal access tokens

Permissions

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

API 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

API 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

API 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

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).

Developer Tools Integration

user:read tokens:read tokens:write tokens:delete

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

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.

Important Notes:

• 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

Quick Start

Rate Limits