Getting Started

Walk through receiving your Rialto credentials and making your first token exchange.

This guide walks you from receiving your Rialto credentials to a working token exchange.

Prerequisites

Credentials from Rialto -- you have received an org_id and api_key
An OIDC-compliant identity provider (Cognito, Auth0, Okta, Azure AD, etc.)
Your IdP issues JWT ID tokens containing sub and email claims

Important: You need ID tokens, not access tokens. ID tokens contain user identity claims like email. Access tokens (e.g., Cognito tokens with token_use: "access") typically do not include email and will be rejected.

Step 1: Store Your API Key

Your API key was provided when Rialto registered your organization. It follows this format:

rialto_ak_<org_id>_<random>

Store it securely -- in a vault, secrets manager, or encrypted environment variable. The API key is shown only once during registration and cannot be retrieved later.

Step 2: Exchange Your First Token

Obtain an ID token from your IdP for one of your users, then exchange it for Rialto tokens:

curl -X POST https://api.rialto.com/identity/auth/exchange \
  -H "Content-Type: application/json" \
  -H "X-API-Key: rialto_ak_550e8400-e29b-41d4-a716-446655440000_K7j9nQ2mP_xYz1aB" \
  -d '{
    "token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Successful response (200):

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 300,
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_expires_in": 1800,
  "scope": "openid email profile aud:identity aud:primary-issuance"
}

On the first exchange for a given user, Rialto automatically creates a user record linked to your organization. Subsequent exchanges for the same email reuse the existing user.

Step 3: Use Rialto Tokens

Use the access_token as a Bearer token on all other Rialto API calls:

curl https://api.rialto.com/identity/users/<user_id> \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

The access token contains custom claims your application can use:

Claim	Description
`org_id`	Your organization ID
`org_name`	Your organization name
`user_id`	Rialto user ID
`email`	User's email address
`kyc_completed`	Whether the user has passed KYC
`accredited`	Whether the user is accredited
`accreditation_verified`	Whether accreditation has been verified

Token lifetimes:

Access token: ~5 minutes
Refresh token: ~30 minutes

When the refresh token expires, exchange a fresh ID token from your IdP.

Step 4: Set Up Webhooks (Optional)

Receive real-time notifications when events occur (KYC approved, subscription funded, etc.) by registering a webhook endpoint:

curl -X POST https://api.rialto.com/notifications/webhooks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <rialto_access_token>" \
  -d '{
    "url": "https://yourapp.com/webhooks/rialto",
    "eventTypes": ["kyc.session.approved", "subscription.created"]
  }'

The response includes a signing_secret for verifying webhook signatures. See the Webhooks Guide for full details.

What's Next

Authentication -- Token exchange deep dive, IdP-specific notes
Webhooks -- Event types, signature verification, retries
KYC & Accreditation -- User verification flows
API Reference -- Full endpoint catalog

Troubleshooting

Error	Status	Cause	Fix
`missing_api_key`	401	`X-API-Key` header not sent	Add the header to your request
`invalid_api_key`	401	Key is wrong, revoked, or has extra whitespace	Verify the key value; contact Rialto if lost
`invalid_token` (token must be a JWT)	400	Token is not a valid JWT (not 3 dot-separated parts)	Ensure you're sending a properly formatted JWT
`invalid_token` (must contain email)	400	Token is missing `email`, `preferred_username`, and `upn` claims	Use an ID token, not an access token
`invalid_token` (must contain sub)	400	Token is missing the `sub` claim	Ensure your IdP includes `sub` in the ID token
`invalid_signature`	401	JWT signature verification failed against your IdP's JWKS	Ensure the token is freshly issued and not tampered with
`token_expired`	401	The ID token has expired	Exchange a fresh token from your IdP
`discovery_failed`	502	Could not reach your IdP's `/.well-known/openid-configuration`	Verify your IdP URL is publicly accessible
`issuer_not_registered`	403	The token's issuer URL is not registered with Rialto	Contact Rialto to register your IdP
`org_mismatch`	403	API key belongs to a different org than the token's issuer	Verify you're using the correct API key for your IdP