Integration Overview explains how third-party applications connect to Onyx through Connect SDK and Onyx ID.
Apps do not receive unrestricted account access.
Every integration is:
- permissioned
- scoped
- revocable
- trust-aware
- visible to the user
An app must request specific access before it can:
- identify a user
- access profile information
- request trust assertions
- send messages
- create app-linked conversations
- access community capabilities
The user reviews the request before access is granted.
Integration
Integration lifecycle board
Move through app identity, scopes, consent, assertions, reachability, webhook delivery, and revocation.
Lifecycle step
App identity
Behavior
App name and redirect URI are configured.
Reason code style
Stable recovery guidance
How Integration Works
A standard integration flow typically includes:
- App registration
- Scope configuration
- User login
- Consent request
- Trust and eligibility checks
- Communication permission checks
- Connected app access
- Permission management and revocation
The app only receives the permissions and assertions approved through Onyx ID.
App Identity
Every connected app must identify itself clearly before requesting access.
The consent flow should show:
- app name
- app identity
- requested permissions
- requested scopes
- intended use
- expiration timing where supported
Apps should not use unclear or misleading consent language.
Unverified or restricted apps may not be able to request certain scopes or communication permissions.
Scopes
Scopes define what an app is requesting.
Supported scope categories can include:
- public profile
- handle access
- display information
- public links
- trust read
- verification assertions
- communication reach
- messaging permissions
- community access
- session access
Apps should request only the permissions required for the intended feature.
Some scopes can require:
- stronger trust state
- account verification
- regulated eligibility
- additional consent review
Unsupported or excessive scope requests can be rejected automatically.
Consent
Every access request requires user consent.
Consent states can appear as:
- pending
- approved
- declined
- revoked
- expired
- step-up required
Users can:
- approve access
- deny access
- revoke permissions
- review connected apps
- review permission history
Some permissions may expire automatically depending on:
- app policy
- account state
- trust level
- regional requirements
Apps must stop using permissions immediately after revocation or expiration.
Assertions
Apps can request limited trust and verification assertions through Onyx ID.
Examples include:
- identity verified
- age verified
- payment eligible
- jurisdiction eligible
- organization verified
Assertions are scoped and permissioned.
Apps receive:
- the approved result
- assertion state
- eligibility status
Apps do not receive:
- raw KYC documents
- unrestricted identity access
- unrelated wallet activity
- unrelated payment history
- private verification evidence
Trust And Eligibility
Some app capabilities depend on:
- account trust state
- verification status
- payment eligibility
- communication permissions
- region
- connected app review state
Trust state can affect:
- messaging permissions
- communication reachability
- payment-linked actions
- organization visibility
- community access
Some integrations may remain unavailable until:
- verification completes
- app review succeeds
- trust state improves
- communication permissions are granted
Reachability
Reachability controls whether an app can communicate with a user.
Reachability states can include:
- none
- identity connected
- messaging enabled
- community member
Communication permissions depend on:
- consent
- trust state
- thread state
- route capability
- community permissions
- feature availability
An app may authenticate successfully while still lacking permission to message the user.
Messaging Access
Some approved apps can:
- create app-linked threads
- send supported messages
- receive delivery events
- receive webhook updates
Messaging capabilities depend on:
- user consent
- app verification
- trust level
- communication route
- thread state
- account restrictions
Apps should not attempt delivery blindly.
The platform can evaluate:
- whether delivery is allowed
- whether consent exists
- whether messaging is restricted
- whether the route supports the action
Before sending messages, apps should validate communication eligibility.
Access Changes
Permissions and eligibility can change over time.
Access can become restricted because of:
- revoked consent
- expired permissions
- insufficient trust
- verification expiration
- app review failure
- rate limits
- thread restrictions
- community moderation
- regional restrictions
- feature gating
Apps must respect updated access state immediately.
A previously approved action may later become:
- restricted
- expired
- unavailable
- permission blocked
Security And Privacy
Connected apps should only receive:
- approved scopes
- approved assertions
- approved communication permissions
- approved visibility
Apps should never receive:
- raw KYC payloads
- unrestricted account access
- private wallet material
- unrelated conversations
- hidden trust signals
- private provider data
The integration system is designed around:
- consent
- scoped access
- revocable permissions
- trust-aware communication
- minimal identity exposure