Scopes define what an approved app is asking to access.
Ask for the smallest set of scopes that supports the user action. If the user declines, revokes, or loses eligibility, the app must stop using that access.
Scope Categories
Connect SDK can support scopes for:
- public profile access
- handle access
- display information
- public links
- trust state read access
- verification assertions
- communication reach
- communication messaging
- community access where enabled
- session continuity
Not every scope is available to every app.
Some scopes require review, stronger app trust, user consent, or additional account eligibility.
Least-Privilege Requests
Partners should request only what the feature needs.
For example:
- Use profile scopes when the app needs a user-visible identity.
- Use trust scopes when the app needs a safe account-confidence signal.
- Use assertion scopes when the app needs a specific eligibility result.
- Use communication scopes only when the app needs to contact the user.
Do not bundle extra scopes into a login flow because they might be useful later.
Permission States
Permission state can appear as:
- requested
- granted
- limited
- revoked
- expired
- denied
- unavailable
Apps must check the current state before using the permission.
Previously granted access can change.
Limited Access
Limited access means the app can use only part of what it requested.
Access can be limited because:
- the user approved fewer scopes
- the app lacks approval
- the account does not meet eligibility requirements
- the region does not support the requested feature
- the scope is gated
The partner app should continue only with available actions.
Unavailable Scopes
A scope can be unavailable if Onyx has not approved it for the app, market, account, or feature.
Unavailable scopes should not be retried without a change in approval, consent, eligibility, or configuration.
User Visibility
Users should be able to understand what an app can access.
Partner experiences should use clear scope labels, plain descriptions, and a visible path to review or revoke connected access.