OAuth Scopes Reference

Reference of available OAuth scopes organized by provider and permission level.

Service-Configured Scopes

Services can request additional OAuth scopes beyond the defaults. These scopes determine what data your application can access from the OAuth provider.

Configuring Scopes

Configure scopes when creating or updating a service:

{
  "slug": "my-app",
  "name": "My Application",
  "oauth_scopes": {
    "github": ["user:email", "read:org"],
    "google": ["email", "profile", "calendar.readonly"],
    "microsoft": ["User.Read", "Calendars.Read"]
  }
}

GitHub Scopes

Default Scopes

Scope	Description	Granted by Default
`user:email`	Read user email addresses	Yes

Additional Scopes

Scope	Description	Use Case
`read:user`	Read user profile data	Display profile info
`user`	Read/write user profile	Profile management
`read:org`	Read organization membership	Team features
`repo`	Full repository access	CI/CD integrations
`public_repo`	Public repository access	Open source tools
`read:repo_hook`	Read repository webhooks	Monitoring
`write:repo_hook`	Create/edit webhooks	Automation
`admin:org`	Full organization management	Enterprise admin
`gist`	Create/edit gists	Code sharing
`notifications`	Access notifications	Notification sync
`workflow`	Update GitHub Actions workflows	CI/CD

Scope Categories

User Scopes:       read:user, user:email, user:follow
Repo Scopes:       repo, public_repo, repo:status, repo_deployment
Org Scopes:        read:org, write:org, admin:org
Hook Scopes:       read:repo_hook, write:repo_hook, admin:repo_hook
Notification:      notifications
Gist:              gist
Workflow:          workflow

Google Scopes

Default Scopes

Scope	Description	Granted by Default
`email`	Read user email	Yes
`profile`	Read basic profile	Yes
`openid`	OpenID Connect	Yes

Additional Scopes

Scope	Description	Use Case
`https://www.googleapis.com/auth/calendar.readonly`	Read calendar events	Calendar integration
`https://www.googleapis.com/auth/calendar`	Full calendar access	Calendar management
`https://www.googleapis.com/auth/drive.readonly`	Read Drive files	File browsing
`https://www.googleapis.com/auth/drive`	Full Drive access	File management
`https://www.googleapis.com/auth/gmail.readonly`	Read Gmail messages	Email processing
`https://www.googleapis.com/auth/contacts.readonly`	Read contacts	Contact sync
`https://www.googleapis.com/auth/spreadsheets.readonly`	Read Sheets	Data import
`https://www.googleapis.com/auth/admin.directory.user.readonly`	Read Workspace users	Enterprise sync

Shortened Aliases

For convenience, AuthOS accepts shortened scope names:

Shorthand	Full Scope
`calendar.readonly`	`https://www.googleapis.com/auth/calendar.readonly`
`calendar`	`https://www.googleapis.com/auth/calendar`
`drive.readonly`	`https://www.googleapis.com/auth/drive.readonly`
`drive`	`https://www.googleapis.com/auth/drive`
`gmail.readonly`	`https://www.googleapis.com/auth/gmail.readonly`

Microsoft Scopes

Default Scopes

Scope	Description	Granted by Default
`User.Read`	Read user profile	Yes
`email`	Read user email	Yes
`openid`	OpenID Connect	Yes
`profile`	Read basic profile	Yes
`offline_access`	Refresh tokens	Yes

Additional Scopes

Scope	Description	Use Case
`User.ReadBasic.All`	Read basic profiles of all users	Directory browsing
`Calendars.Read`	Read calendar events	Calendar integration
`Calendars.ReadWrite`	Full calendar access	Calendar management
`Mail.Read`	Read email messages	Email processing
`Mail.Send`	Send email	Email automation
`Files.Read`	Read OneDrive files	File browsing
`Files.ReadWrite`	Full file access	File management
`Group.Read.All`	Read all groups	Team features
`Directory.Read.All`	Read directory data	Enterprise sync
`Sites.Read.All`	Read SharePoint sites	Document access

Permission Types

Microsoft scopes come in two types:

Delegated Permissions (user context):

User.Read, Calendars.Read, Files.Read
Act on behalf of signed-in user

Application Permissions (daemon/service):

User.Read.All, Directory.Read.All
Require admin consent, no user present

API Key Scopes

API keys have separate scopes from OAuth:

Available API Key Scopes

Scope	Description
`read:users`	List and retrieve user data
`write:users`	Create, update, delete users
`read:subscriptions`	Read subscription data
`write:subscriptions`	Manage subscriptions
`read:analytics`	Access analytics data

Example API Key Creation

{
  "name": "Production API Key",
  "scopes": ["read:users", "write:users", "read:subscriptions"]
}

Requesting Provider Tokens

Once a user authenticates with extended scopes, retrieve the provider token:

GET /api/provider-token/github
Authorization: Bearer {jwt}

Response:

{
  "access_token": "gho_16C7e42F292c6912E7710c838347Ae178B4a",
  "scopes": ["user:email", "read:org"],
  "provider": "github",
  "expires_at": "2025-01-20T10:30:00Z"
}

Best Practices

Request minimal scopes - Only request what you need
Explain scope usage - Tell users why you need each scope
Handle scope denial - Users may decline optional scopes
Refresh tokens - Google and Microsoft tokens expire; use refresh
Scope changes - Users must re-authenticate if scopes change