An Onyx partner integration starts with an connected app identity and ends with a user-controlled connection.
The app requests only the scopes it needs. The user reviews the request. Onyx returns only granted access, current state, and safe eligibility results.
Integration Path
The standard path is:
- Create an app identity.
- Configure app profile, redirect URIs, and scopes.
- Sign the user in with Onyx.
- Request consent for the required scopes.
- Check trust and eligibility.
- Check communication permission.
- Create app-linked access where enabled.
- Send configured messages where allowed.
- Receive webhook events.
- Handle revocation and expiration.
Each step depends on current account, app, and permission state.
App Identity
Every app must identify itself before requesting access.
The app identity includes:
- app name
- app description
- verified domain
- redirect URIs
- allowed origins
- granted scopes
- review status
Users should understand which app is requesting access.
Scope Configuration
Scopes define what the app wants to access.
Partners should configure scopes before requesting consent.
Unsupported, excessive, duplicated, or unclear scope requests can be rejected.
User Consent
Consent gives the user control over connected access.
The consent flow should show:
- app name
- requested permissions
- intended use
- expiration timing when the permission has an expiration
- user action required
The app must respect denied, revoked, expired, or limited access.
Trust And Eligibility
Some integrations need trust or verification assertions.
Granted assertions can answer specific eligibility questions, such as whether identity, age, jurisdiction, organization, or payment eligibility requirements are met.
The app receives only the scoped assertion result.
Communication Access
Communication access is separate from login.
An app may sign a user in and still lack permission to message that user.
Before messaging, check:
- consent
- reachability
- app configuration
- thread state
- reason codes
Access Changes
Access can change after access is granted.
Access can become unavailable because of:
- revoked consent
- expired permission
- app review changes
- trust requirements
- regional limits
- feature gating
- thread restrictions
Partners should check current state before each protected action.
Production Readiness
Before production, confirm:
- app identity is configured
- redirect URIs are correct
- domains are verified
- scopes match the feature
- consent copy is configured
- webhooks are tested
- revocation works
- blocked actions show clear reason codes