Connect SDK | Onyx Docs

Connect SDK is the application integration layer for Onyx.

It allows approved apps to:

authenticate users with Onyx ID
request scoped permissions
verify trust and eligibility state
check communication reachability
create app-linked conversations
send policy-approved messages
receive delivery and webhook events

Connect SDK is not a general identity export system.

Every interaction is:

permissioned
scoped
revocable
visible to the user

Apps only receive the permissions and identity assertions explicitly approved through Onyx ID.

Connect SDK

Consent request simulator

Approve, deny, revoke, or expire a scoped app request and watch the permission state update.

Requesting app

Onyx Partner App

Requested scope

Profile

Scoped

Requested scope

Trust read

Scoped

Requested scope

Messaging permission

Scoped

requested

Apps receive only approved scopes. Revoked or expired permissions block access immediately.

What Connect SDK Does

Connect SDK provides:

login and authorization flows
app consent handling
capability checks
communication permission checks
pre-send simulation
app-thread messaging
webhook delivery
trust and eligibility assertions

The SDK coordinates:

Onyx ID
Chat
permissions
communication routing
trust state
delivery policy

Backend enforcement still happens inside the Onyx API runtime. The SDK does not bypass account policy or communication rules.

Developer Flow

The standard integration flow is:

Create an app identity
Configure redirect URIs and scopes
Authenticate the user with Onyx ID
Request consent
Check reachability and permissions
Simulate delivery eligibility
Create a conversation thread
Send a message
Receive webhook and delivery events

The SDK is designed so developers can complete the first successful integration without reading internal implementation details.

Authentication And Login

Connect SDK supports OAuth and OpenID Connect authorization flows with PKCE support.

The SDK can generate login URLs using:

client ID
redirect URI
PKCE values
nonce
state
requested scopes

The application is responsible for:

session handling
token storage
refresh handling
redirect completion

Connect SDK does not expose unrestricted identity access after login.

Scopes And Permissions

Apps request access through scopes.

Supported scope categories can include:

profile
handle
display information
public links
trust read
verification assertions
communication reach
communication messaging
community access
session access

Apps should request only the permissions required for the intended feature.

Permission states can appear as:

requested
granted
limited
revoked
expired
denied

Apps must respect revoked, expired, unavailable, or insufficient-trust states.

Consent Flow

Every permission request requires explicit user consent.

Consent prompts should show:

app name
requested scopes
requested account access
intended use
expiration timing where supported

Users can:

approve access
deny access
revoke permissions
review connected apps
review permission history

Unsafe or malformed consent requests can be rejected automatically.

Examples include:

unsupported scopes
duplicate scopes
invalid redirect configuration
excessive scope requests
unsafe consent language

Connected apps should never receive unrestricted identity access.

Trust And Eligibility

Connect SDK can expose limited trust and eligibility assertions through Onyx ID.

Examples include:

identity verified
payment eligible
age verified
jurisdiction eligible
organization verified

Apps only receive approved assertions.

Apps should not receive:

raw KYC documents
unrestricted account data
private verification evidence
unrelated wallet activity
provider internals

Trust assertions depend on:

account trust state
verification status
regional eligibility
consent scope
account permissions

Communication Permissions

Communication access is handled separately from identity login.

An app may authenticate successfully but still lack permission to:

message users
create threads
send notifications
access communication routes

Before messaging becomes available, Connect SDK can evaluate:

consent state
trust level
communication reachability
route capability
thread restrictions
delivery policy

This prevents apps from sending messages blindly or creating unauthorized communication flows.

Pre-Send Simulation

Connect SDK supports pre-send simulation before a message is sent.

Simulation can evaluate:

whether delivery is allowed
whether consent exists
whether the recipient is reachable
whether the route supports the action
whether the app trust level is sufficient

The SDK can return:

allowed
blocked
restricted
unsupported
consent required
trust insufficient

The SDK encourages simulation before live sends to reduce failed delivery attempts.

Messaging And Threads

Approved apps can:

create app-linked conversation threads
send messages into supported conversations
receive delivery updates
receive thread lifecycle events

Message actions remain subject to:

communication policy
trust restrictions
route capability
thread state
recipient permissions

Thread state can affect delivery.

Examples:

muted
blocked
archived
closed
restricted

Some routes may support:

rich messaging
media
identity-linked actions

Others may support:

text only
limited fallback communication

Delivery And Webhooks

Connect SDK supports webhook delivery for:

message events
delivery updates
thread lifecycle events
trust changes
consent changes
permission revocations

Webhook systems can include:

signing validation
delivery retries
test delivery
event history
audit visibility

Delivery posture can vary depending on:

recipient trust
communication route
muted state
delivery policy
account restrictions

The SDK should return stable reason codes and recovery guidance instead of generic failures.

Reason Codes And Errors

Common reason codes can include:

NO_CONSENT
CONSENT_EXPIRED
APP_NOT_VERIFIED
INSUFFICIENT_TRUST
THREAD_BLOCKED
THREAD_CLOSED
FEATURE_GATED

Errors can include:

HTTP request failures
validation failures
token failures
scope validation errors
unsupported route errors
delivery policy failures

Applications should show a clear recovery path instead of retrying blindly.

Gated Features

Some Connect capabilities remain:

gated
beta-only
environment-restricted
operator-controlled

Examples can include:

support-agent execution
community execution
event subscriptions
advanced trust integrations
expanded messaging permissions

Disabled capabilities should return explicit controlled states instead of failing silently.

Security And Privacy

Connect SDK is designed around:

scoped access
explicit consent
revocable permissions
trust-aware communication
limited identity exposure

Apps should never receive:

raw KYC payloads
unrestricted profile access
private wallet material
unrelated communication history
private device state
internal provider data

The SDK exists to connect trusted apps to Onyx users safely without exposing unnecessary account information.