Skip to content
Radioso Docs home
Open app

Auth and sessions

These routes are the entry point for account creation, session establishment, invitation inspection, invitation acceptance, and the signed-in person’s own profile.

How it works

Check registration or inspect an invitation

Check registration availability before presenting open signup. Registration creates the initial organization and default workspace when the deployment permits it. Invitation inspection lets a user confirm the target organization before joining it.

Establish the session

When registration reports that verification is required, verify the email address and then log in. Development registration can report that verification is complete and return the session cookie directly. Invitation acceptance and password reset confirmation also return session cookies.

Use the session for account and workspace routes

Once the cookie is stored, use it for workspace management, API-access lifecycle, provider-secret, connector, public-launch rotation, and signing-key reveal flows.

Production registration does not establish browser or cookie-jar state. Development auto-verification establishes the session during registration; login, invitation acceptance, and password reset confirmation do the same in their respective flows. These session flows are separate from the personal-token and service-credential flows used by eligible API and SDK calls.

Examples below call https://api.radioso.ai, the hosted EU instance. Use https://api-us.radioso.ai for the US-hosted instance, or your own origin when self-hosting — http://localhost:8080 for a local deployment.

Check registration availability

bash
curl -sS https://api.radioso.ai/api/v1/auth/registration

The endpoint returns { "available": true } or { "available": false } and uses Cache-Control: no-store because availability can change as the server is initialized.

On an open-source server, registration is available only while the deployment has no organization. The first successful signup creates the server’s sole organization and default workspace. Later users must join that organization through an invitation. Enterprise Edition keeps registration available even when organizations already exist.

Register

Use registration when GET /api/v1/auth/registration reports that open registration is available.

bash
curl -sS \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"verysecurepassword","organizationName":"Acme","displayName":"Ada Lovelace"}' \
  https://api.radioso.ai/api/v1/auth/register

organizationName and displayName are optional. The required fields are email and password. displayName is the name teammates see for you in the dashboard and visitors see on your replies, and it follows the rules in Your profile.

Registration returns account and default workspace bootstrap data plus requiresEmailVerification. Production returns true, sends a verification email, and does not set a session cookie. The documented development stack returns false, persists the new password user’s verification state, and sets the session cookie immediately.

On an initialized open-source server, registration returns 403 with code: "forbidden". An organization owner or admin must invite the new user instead. Invitation acceptance joins the existing organization and does not create another one.

Password reset is also available from the open-source auth API:

  • POST /api/v1/auth/password-reset/request
  • POST /api/v1/auth/password-reset/confirm

The request endpoint always returns 202 Accepted with { "accepted": true }, including for unknown email addresses. The confirm endpoint sets a new session cookie after a valid reset and revokes older sessions for that user. A login that was already in flight when the reset committed answers 401 with Invalid email or password, the same as the replaced password would.

Email verification is available through:

  • POST /api/v1/auth/email-verification/resend
  • POST /api/v1/auth/email-verification/verify

Verification records email ownership. Normal login requires a verified email address.

Log in

Use login when the account already exists.

bash
curl -sS -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com","password":"verysecurepassword"}' \
  https://api.radioso.ai/api/v1/auth/login

The login request can also include preferredWorkspaceId or preferredAccountId when you want to restore a known context.

The response names where the session landed — accountId, organizationName, and the workspace — along with userId and displayName, the name you set on your profile or null. Every response that signs you in carries the same fields: registration, invitation acceptance, password reset confirmation, and the organization create and switch routes. A client can show who signed in straight from that response.

Sign out

bash
curl -sS -b cookies.txt -c cookies.txt -X POST https://api.radioso.ai/api/v1/auth/logout

Sign-out revokes the session the cookie names, so that cookie value is refused from then on, even if someone replays it. The response is 204 with a Set-Cookie that clears the cookie in the browser or cookie jar. Only that session ends: the same person’s sessions on other devices stay signed in, and signing out records an auth.logout audit event on the organization the session was on.

The call is safe to repeat. With no cookie, an unknown cookie, or a session that already ended, it still answers 204 and clears the cookie, because the caller already holds no usable session.

Every response carries the clearing Set-Cookie, failures included. A database outage answers 503 and any other fault answers 500; either way the browser or cookie jar no longer holds the session, but the server-side session can stay live until it expires, which matters if a copy of the cookie exists elsewhere. A client that must be sure the session ended keeps its copy of the cookie value and repeats the call on a 5xx.

The dashboard’s Sign out menu item calls this route, then returns to the sign-in screen, where a reload stays signed out. If the call fails, the dashboard still signs the browser out and logs the failure to the browser console, and the clearing cookie in the response keeps a reload signed out.

Your profile

Your profile holds the name teammates see for you in the dashboard, and the name visitors see on a reply you send them from the Inbox. Read it with the session cookie:

bash
curl -sS -b cookies.txt https://api.radioso.ai/api/v1/auth/profile

The response carries userId, email, and displayName. displayName is null until you set one. In the meantime the dashboard labels you by email, and your replies to visitors are signed with your organisation’s name — a visitor never sees your email.

Set or change the name with PATCH:

bash
curl -sS -b cookies.txt -X PATCH \
  -H 'Content-Type: application/json' \
  -d '{"displayName":"Ada Lovelace"}' \
  https://api.radioso.ai/api/v1/auth/profile

The response is the updated profile. Radioso trims the name before storing it, and an empty string or null clears it. Any script works, and joiners inside a name stay put: the zero-width joiner in an emoji sequence such as 👩‍💻, or the non-joiner in a Persian name such as می‌خواهم.

Teammates see the name without the email beside it, so the rules refuse anything that would let one person read as another. Each of these returns 400 with a message naming the rule:

  • more than 80 characters
  • a control character, such as a line break or tab
  • a text-direction override, embedding, or isolate (U+202A to U+202E, U+2066 to U+2069)
  • nothing visible, such as only zero-width spaces or Hangul fillers
  • an email address anywhere in it, such as dana@corp.com or Dana dana@corp.com, including one written with lookalike characters such as a fullwidth ＠ or an ideographic full stop; Dana @ Acme is fine

A body with any field besides displayName returns 400 as well.

GET /api/v1/auth/session returns the same displayName next to the account and workspace the session lands on.

The name belongs to you rather than to one organization, so every organization you belong to shows the change. Each of them records its own auth.profile_updated audit event, which names the changed field and never its value.

Profile routes accept only the signed-in session. Personal and service credentials act for a workspace, so they have no profile to read or edit. Reading the profile works from any session. Changing it needs a session on an organization you still belong to: a session on one that removed you gets 401 with Active account membership is required, and switching to an organization you belong to clears it.

Invitation flow

In practice, the invitation flow has two steps:

  1. Read the invitation details with GET /api/v1/auth/invitations/{invitationToken}.
  2. Accept it with POST /api/v1/auth/invitations/{invitationToken}/accept.

The accept request establishes a session for the joined account. When the invitation creates a new login, the body can also carry displayName; an existing login keeps the name it already has.

Endpoint reference

The API Reference lists the fields on each register, login, profile, and invitation payload.

text
GET   /api/v1/auth/registration
POST  /api/v1/auth/register
POST  /api/v1/auth/login
POST  /api/v1/auth/logout
GET   /api/v1/auth/session
GET   /api/v1/auth/profile
PATCH /api/v1/auth/profile
GET   /api/v1/auth/invitations/{invitationToken}
POST  /api/v1/auth/invitations/{invitationToken}/accept

Common failure modes

  • 400 usually means the request body is incomplete or malformed, or a display name breaks the naming rules above.
  • 401 usually means the credentials are wrong, or the invitation accept flow is no longer valid. A profile change also returns 401 when the session’s organization no longer counts you as a member.
  • 403 from registration means open registration is closed and the user needs an invitation. Login can also return 403 when email verification is required.
  • 404 means the invitation token does not exist.
  • 409 usually means the account or invitation state is in conflict with the requested action.
  • 503 means the database is unavailable. Sign out answers it and still clears the session cookie.