OAuth Scopes Reference

Scopes define what data and actions your OAuth application can access. Request only the scopes your app needs—users are more likely to authorize apps with limited, focused permissions.

#How scopes work

• Scopes are requested during the authorization flow
• Users see the requested permissions before authorizing
• Your app can only access data allowed by granted scopes
• Scopes cannot be upgraded without re-authorization

#Scope format

Scopes follow the pattern resource.permission:

• transactions.read — Read transaction data
• invoices.write — Create, update, delete invoices

#Available scopes

#Transactions

Use cases: Financial dashboards, expense tracking, receipt management

#Invoices

Use cases: Invoice automation, payment reminders, accounting sync

#Customers

Use cases: CRM integration, customer portals, contact sync

#Bank Accounts

Use cases: Cash position monitoring, balance alerts

#Documents

Use cases: Document management, backup tools, OCR integrations

#Inbox

Use cases: Receipt processing, automated matching

#Tracker Projects

Use cases: Project management integration, resource planning

#Tracker Entries

Use cases: Time tracking apps, timesheets, billing automation

#Teams

Use cases: Team management, onboarding tools

#Users

Use cases: User management, access control

#Tags

Use cases: Custom categorization, workflow automation

#Reports

Use cases: Financial dashboards, investor updates, forecasting

#Search

Use cases: Global search, data discovery tools

#Notifications

Use cases: Notification aggregators, alert systems

#Meta scopes

For apps that need broad access, meta scopes provide convenient shortcuts:

Use meta scopes sparingly. Most apps should request specific scopes.

#Requesting scopes

Include scopes in the authorization URL as a space-separated list:

https://luma.waytogrow.es/oauth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=transactions.read%20invoices.read%20customers.read&
  state=STATE

URL-encode the scope parameter (spaces become %20).

#Scope validation

When users authorize your app:

1. LUMA validates requested scopes against your app's registered scopes
2. Invalid or unregistered scopes cause authorization to fail
3. Users see exactly what permissions they're granting

If you need additional scopes later, users must re-authorize your app.

#Scope combinations

#Financial dashboard

transactions.read invoices.read bank-accounts.read reports.read

#Invoice automation

invoices.read invoices.write customers.read customers.write

#Time tracking integration

tracker-projects.read tracker-projects.write tracker-entries.read tracker-entries.write

#Accounting export

transactions.read invoices.read customers.read documents.read

#Full read-only access

apis.read

#Best practices

#Request minimal scopes

Only request what you need. Users trust apps that ask for limited permissions.

Good: transactions.read for a spending tracker

Avoid: apis.all when you only need to read transactions

#Separate read and write

If your app only displays data, don't request write scopes:

transactions.read invoices.read

#Group related scopes

If you need invoices, you likely need customers too:

invoices.read invoices.write customers.read

#Document your requirements

Tell users why you need each scope in your app's description or onboarding flow.

#Checking granted scopes

The token response includes the granted scopes:

{
  "access_token": "mid_at_xxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "mid_rt_xxxxx",
  "scope": "transactions.read invoices.read"
}

Check this against your requested scopes to confirm what was granted.

#Related

• Build an OAuth App — Getting started guide
• OAuth API Endpoints — Technical reference
• API Reference — Full API documentation