Connect SDK is the connected app integration layer for Onyx ID.
Use it when your app needs to sign a user in with Onyx, request scoped account access, check trust or eligibility, create app-linked conversations, or receive event updates.
Connect SDK does not export the full Onyx account.
Every access path is scoped, consented, revocable, and controlled by Onyx account state.
What Connect SDK Supports
Connect SDK supports:
- Sign in with Onyx
- scoped profile access
- handle access
- trust and verification assertions
- consent requests
- permission state checks
- communication reach checks
- pre-send checks
- app-linked conversations
- connected app messages
- webhook events
Not every capability is available to every app.
Standard Flow
A typical integration follows this path:
- Create an app identity.
- Configure redirect URIs and allowed scopes.
- Sign the user in with Onyx.
- Request consent for the scopes your app needs.
- Check consent, trust, and reachability.
- Run a pre-send check before messaging.
- Create an app-linked conversation.
- Send an configured message.
- Receive webhook and delivery events.
The app should stop whenever the current state blocks the action.
Login Is Not Permission
Sign-in confirms that the user can access an Onyx account.
It does not grant messaging permission, trust assertions, payment eligibility, or unrestricted profile access.
Request those permissions separately when the user action requires them.
Scoped Access
Apps request access through scopes.
Scope categories include:
- profile
- handle
- public links
- trust read
- verification assertions
- communication reach
- communication messaging
- community access where enabled
- session continuity
Request only what the app needs for the current feature.
Consent
Consent keeps connected app access visible to the user.
A consent request should show:
- app name
- requested scopes
- intended use
- requested account access
- expiration timing when the permission has an expiration
Users can review, deny, revoke, or let access expire.
Messaging
Messaging access requires consent and a current communication permission.
Before sending, the app should check:
- consent state
- user reachability
- message intent
- thread state
- app configuration
- current reason codes
If the message is blocked, use the reason code to choose the next action.
Webhooks
Webhooks can notify your app about configured event types.
Events include:
- consent changes
- message outcomes
- delivery updates
- thread lifecycle changes
- app review changes
Partners should validate webhook authenticity where signing is enabled and handle retries safely.
Privacy Limits
Apps should not receive:
- unrestricted account access
- identity documents
- private verification evidence
- private wallet material
- unrelated payment history
- unrelated communication history
- private device or session state
Connect SDK exists to give trusted apps controlled access without exposing the rest of the account.