Authentication

Radioso has more than one authentication model because it serves more than one audience. A person in the dashboard, a script calling the API, and an anonymous visitor on your website all need to be trusted differently, so the web app, API, public chat, and Enterprise embed flows don’t share credentials. Pick the mode that matches who’s knocking.

Main access modes

• Session-based access for the product UI
• Personal tokens and service-account credentials for role-aware workspace automation
• Delegated Operator MCP grants for Ray tools in a user’s workspace
• Role-free agent credentials for REST or MCP chat with one agent
• Anonymous public chat and Enterprise embed flows for customer-facing agent experiences

Session-based access

Use sessions when a person is interacting with the product UI.

The main auth routes are:

• registration availability
• register
• login
• invitation accept

Use GET /api/v1/auth/registration to check whether open registration is available. It returns { "available": true } or { "available": false } without requiring authentication, so you can decide whether to show signup before anyone tries it.

On an empty open-source server, the first registration creates the server’s sole organization and default workspace. Open registration then closes, and later users join the existing organization by invitation. Enterprise Edition keeps open registration available and lets signed-in users create additional organizations. Authorized users can create additional workspaces in either edition; the edition boundary applies to organizations, not workspaces.

Production registration sends a verification email and does not set a session cookie. The documented development entrypoints enable automatic verification for newly registered password users and return the session cookie immediately. The backend also sets the cookie on successful login, invitation acceptance, and password reset confirmation. Invitation acceptance has two entry points — one that takes a password and one that takes the session of an already signed-in invitee — and Accept an invitation covers which to call. Open-source Radioso includes password reset and email verification endpoints, and normal sign-in requires a verified email address; development registration satisfies that requirement by persisting the verification state rather than bypassing login checks.

Sign-in paths that redirect the browser hand back a cookie and no body. GET /api/v1/auth/session reports who the current cookie belongs to — the user’s id and email, the account it lands on, and that account’s workspace — so a client can recover the signed-in identity without asking for a credential. It answers 401 when there is no live session.

Provider sign-in

A deployment can also accept a sign-in assertion from an external identity provider. Radioso stores the link as a (provider, subject) pair against the user, and the subject is the identifier of record: providers keep it stable for the life of the account, while the address on it can be reassigned.

That ordering is what a returning user feels. On the first provider sign-in Radioso matches by verified email — linking the provider to an existing password login, or creating a user when the address is new — and records the link. On every sign-in after that the subject decides, so someone whose work address changed lands in the account they already have instead of a fresh empty one. The new address is kept on the link; the login email itself stays put, because rewriting it could collide with another user.

A user created this way has no password. They can adopt one through the password reset flow, and until they do, provider sign-in is their only credential — which is why accepting an invitation reports the linked providers alongside the password requirement.

Confirming a password reset drops the user’s provider links along with their sessions. A reset proves control of the mailbox right now, and the links are a credential like any other: one established while an address was briefly held by someone else should not outlive the password it sat beside. Signing in with the provider again re-establishes the link.

Personal tokens and service accounts

Use a personal token for automation that should follow a person’s live workspace membership. Use a service account for CI, scheduled jobs, and services that need a stable non-human identity. Both use the workspace role model and authenticate eligible role-aware API routes without a browser session.

If a credential is exposed, revoke or immediately rotate it from its settings page. Service accounts can also hold overlapping credentials so you can deploy a replacement before revoking the old value.

Operator MCP OAuth

Use Operator MCP when an external engine should work with Ray’s governed operator tools in a workspace. Start in Settings → API access → Radioso MCP, select a client surface, and follow its setup artifact. The setup contains the canonical /operator/mcp resource and client-specific instructions; authorization happens in the browser and the client receives OAuth tokens after you approve the request.

Consent is tied to the client identity, signed-in user, selected workspace, and requested capability categories. The catalog has operator:read for bounded state, operator:probe for diagnostics, operator:propose for reviewable routine, retrieval, and publication preparation, operator:write for a bound reviewed operation’s execution, outcome, and cancellation, and operator:act for the version-fenced triage-state action. A write-authorized client must show the exact review and obtain conversational confirmation before it executes it. You can approve a subset of requested categories; when the client requests refresh access, approving the connection includes it.

The API access card shows safe grant metadata—client, workspace, creation time, and recent use. Revoke your own grant there; an owner or administrator can revoke another user’s grant without viewing credentials or approving consent for them. The client chooser is setup state only: it never labels a client connected until a validated OAuth grant exists.

Agent chat credentials

Use a REST-audience agent credential for POST /api/v1/agents/{agentId}/chat, or an MCP-audience credential for the standalone MCP server’s ask_agent tool. Both are bound to exactly one agent, require an expiry, and carry no member or admin role.

A signed-in user with agent-manage permission issues, rotates, or revokes these credentials from the agent’s Channels page. The plaintext secret is shown once and stored only as a hash. Personal tokens and service-account credentials are not accepted for agent chat, and agent credentials cannot call workspace-administration APIs. Operator-minted agent credentials are static bearers; Radioso does not require OAuth for them.

Public chat and embed access

Public website chat doesn’t use an operator session. It relies on workspace-controlled public settings, public chat tokens, or embed session flows that are scoped to the workspace configuration.

That’s the right model for customer-facing agents, and the wrong one for operator automation, because a public visitor should never hold an operator’s credentials. The hosted website widget is an Enterprise Edition surface; anonymous public chat uses the same public-session model without the widget routes.

Choose the right mode

• Use sessions for humans in the app.
• Use personal tokens or service-account credentials for eligible REST and SDK automation.
• Use Operator MCP OAuth when an external engine needs Ray’s current, workspace-scoped operator capabilities.
• Use a REST or MCP agent credential when a client should only converse with one agent.
• Use public chat or Enterprise embed flows for customer-facing agents.

Start points

• API first success
• API Reference
• Public chat and embed API