Authentication

Rialto uses a token exchange pattern: your users authenticate with your identity provider, and you exchange their ID token for Rialto tokens.

Token Exchange Flow

User ──► Your App ──► Your IdP ──► ID Token
                                      │
                         POST /identity/auth/exchange
                         X-API-Key: rialto_ak_...
                         { "token": "<id_token>" }
                                      │
                                      ▼
                              Rialto Identity
                         (validates JWT via OIDC/JWKS)
                                      │
                                      ▼
                         { access_token, refresh_token }

1. User authenticates with your IdP
2. Your backend obtains the user's ID token
3. Your backend calls POST /identity/auth/exchange with the ID token and your X-API-Key
4. Rialto validates the JWT signature via OIDC discovery and JWKS
5. User is auto-created on first exchange (linked by email)
6. Rialto returns an access_token and refresh_token

API Key

Your API key identifies your organization on every token exchange request.

The API key identifies your organization. The ID token identifies the user. Both are required.

Token Exchange Request

curl -X POST https://api.rialto.com/identity/auth/exchange \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <your_api_key>" \
  -d '{ "token": "<id_token>" }'

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"
}

Rialto Token Claims

The access_token includes these custom claims:

Use these claims to gate UI features. For example, check kyc_completed and accredited before allowing a user to subscribe to offerings.

Token Lifetimes

ID Token Requirements

Your ID token must meet these requirements:

IdP-Specific Notes

AWS Cognito

Use the ID token (token_use: "id"), not the access token (token_use: "access"). Cognito access tokens do not contain the email claim.

• Issuer URL: https://cognito-idp.<region>.amazonaws.com/<user-pool-id>
• The token exchange endpoint will detect access tokens and include a hint in the error message

Auth0

Auth0 ID tokens are always JWTs and include email by default.

• Issuer URL: https://<tenant>.auth0.com/
• Ensure the email scope is requested during authentication

Okta

• Issuer URL: https://<org>.okta.com/oauth2/default
• If using a custom authorization server, the issuer URL will differ

Azure AD / Entra ID

• Issuer URL: https://login.microsoftonline.com/<tenant-id>/v2.0
• Ensure the email claim is included (may require configuring optional claims)

Google

• Issuer URL: https://accounts.google.com
• ID tokens always include email when the email scope is requested

Audience Scopes

When your organization was registered, audience scopes were configured (default: ["identity"]). The exchanged Rialto token includes these as aud:<scope> in the scope field:

scope: "openid email profile aud:identity aud:primary-issuance"

To update your audience scopes, contact Rialto staff or use:

PATCH /identity/auth/idp/<org_id>
{ "audience": ["identity", "primary-issuance", "custom-scope"] }

The "identity" audience is always included.

Error Reference