Developer Hub
Login with raia
Let people sign in to your app with their raia account using standard OpenID Connect (OIDC) — for eligible integrations; confirm registration requirements with raia.
Not yet documented — confirm the identity contract. This repository does not include the identity provider implementation or a verified discovery document. Confirm issuer, registration eligibility, redirect URI rules, scopes, and supported flows with raia before implementing sign-in. The callback URL below is an example, not a raia endpoint.
Note
Only Enterprise partners qualify for this feature.
What it is
Login with raia lets people sign in to your software with the raia account they already have. Your product shows a "Login with raia" button, the user signs in on raia, and they land back in your app, signed in.
It is meant to work like "Sign in with Google" or "Sign in with Microsoft". raia describes it as a standard OpenID Connect (OIDC) identity provider, so a standard OIDC client library should be able to connect once your application is registered. That means there's no custom SDK to learn.
Why it matters
Your users already work in raia every day. They should open your product without making and remembering another password.
For your users
- One account and one password for raia and your product.
- Sign-in takes a couple of clicks. The raia screen shows your app's name and logo, so people know who they're signing in to.
- People who use raia in the US and in the EU can both sign in.
For your product team
- Less to build. You get raia's sign-in screens, email verification, and password handling without building your own.
- No proprietary SDK. Standard OIDC fits most stacks: Node, Python, .NET, Java, Ruby, Go, and the auth platforms that support OIDC providers.
- You keep control. raia confirms who the user is, and from there your app runs its own session, roles, and data.
- Less friction from raia user to active user of your product, which helps adoption.
Common use cases
| Use case | What it looks like |
|---|---|
| Companion app or portal | A vertical software company ships a portal, dashboard, or admin tool next to its raia agents. Staff sign in with their raia account. |
| Partner-built tools | An implementation partner builds a custom reporting or review app for a shared customer. Users sign in with raia, and the partner never handles their passwords. |
| Internal tools | A customer's team builds a small internal app (QA review, training tracker) and uses raia as its sign-in instead of standing up its own user store. |
| Account linking | An existing product adds "Login with raia" next to its own login. Returning users link their raia account once and then use either option. |
How it works
- The user clicks Login with raia in your app.
- Your app sends them to the raia sign-in page (with a PKCE challenge).
- The user signs in on raia.
- raia shows your app's name and logo and asks the user to allow or deny.
- raia redirects back to your registered callback URL with a one-time code.
- Your server exchanges the code (plus the PKCE verifier and client secret) for a signed ID token.
- Your app matches or creates the user and starts its own session.
The user signs in and approves on raia. raia sends them back to your app with a one-time code. Your server exchanges the code for a signed ID token, matches or creates the user, and starts its own session.
What your app receives
After sign-in, your app gets a signed ID token with basic identity details. It contains only the details below, and only after the user approves on the raia screen.
| Detail | Requested with | How to use it |
|---|---|---|
User ID (sub) | openid | The stable key for the user. Store it and match users on it. Treat it as an opaque string, because EU users' IDs carry a region prefix. |
| Email + whether it's verified | email | Contact details. Link it to an existing account only when the email is verified. |
| Name, given name, family name | profile | Display name. |
| Profile picture | profile | Included only when the user has set an avatar. |
Login with raia identifies the user. It does not grant access to the user's raia agents, conversations, or data.
Security and privacy
Login with raia is described as using the authorization code flow with PKCE, the current recommended OAuth flow. Users type their password only on raia, never in your app. The points below describe the intended requirements; real client enrollment, sign-in, denied-redirect and PKCE verification have not yet been tested for this documentation.
- User consent. Before any detail is shared, the user sees your app's name and logo on raia and chooses to allow or deny.
- PKCE required. Each sign-in is meant to use a one-time proof key (
S256). PKCE aims to stop a code intercepted in transit from being exchanged by anyone who lacks the matching verifier; it is one protection, not a guarantee on its own. - Exact redirect URIs. raia is intended to send users back only to the HTTPS addresses you registered, exactly as written. Confirm wildcard and local-development URI rules during registration, and test that an unregistered redirect is refused.
- Client secret shown once. The documentation describes the secret as displayed once; how it is stored on raia's side has not been verified. Keep it in a secret manager. If it's lost or exposed, ask raia to rotate it; the old secret is meant to stop working, so confirm when it does.
- Can be switched off. raia can disable an application at any time, which stops new sign-ins through it.
- Your session, your rules. raia doesn't issue refresh tokens. Your app creates its own session after sign-in and controls its own logout.
Regions and data residency
raia runs in two regions: Production US and Production EU. By default, one application in the US region is enough. It serves users from both regions.
If your product must keep EU users' personal data inside the EU (for example, under GDPR), ask for a second application in the EU region and send EU users to the EU sign-in address. Check your data-residency requirements before you go live.
Getting started
OAuth applications are registered by the raia team. Here's the path from request to launch:
- Send raia your app details:
- App name and logo URL, which users see on the raia sign-in screen.
- Your exact callback URL(s), for example
https://app.example.com/api/auth/raia/callback. - The region: US by default, or EU as well if data residency requires it.
- Receive your credentials: a Client ID and a Client secret. Store the secret in your secret manager right away, because it's shown only once.
- Connect your app. Point your OIDC client library at the raia issuer URL so it can read the endpoints from the discovery document. Discovery does not configure everything: you still set the Client ID, the client secret (for a confidential client), the registered redirect URI and the scopes you request.
- Add the button. A plain link to your login route, labeled "Login with raia".
- Test and go live. Test a new user, a returning user, a user who cancels on the raia screen, and an EU user signing in through the US app.
| Environment | Issuer URL |
|---|---|
| Production US | https://api.raia2.com/identity |
| Production EU | https://api-eu.raia2.com/identity |
Request the developer integration guide for step-by-step code, a complete Next.js example, a go-live checklist, and troubleshooting.
Scope and FAQ
Does it give my app access to the user's raia agents or data? No. It shares only identity: user ID, email, name, and picture. Use the raia API separately to work with agents.
What scopes can I request? openid, email, and profile. Any other scopes are ignored.
Does it issue refresh tokens? No. Use the sign-in to identify the user, then run your own session.
How does logout work? Sign the user out of your own app. raia has no single-logout endpoint.
Can I use it for local development? Yes, over HTTPS. Expose your local app through a tunnel such as ngrok and register that callback URL temporarily. Confirm whether localhost callbacks are supported during registration.
What if a user already has an account in my app with the same email? Link the two only if raia reports the email as verified. Otherwise, ask the user to sign in the usual way and link raia from their profile. This protects accounts from takeover.
What if our client secret leaks? Ask raia to rotate it and deploy the new one straight away. The old secret is meant to stop working; confirm with raia when it has.