Skip to content
Radioso Docs home
Open app

Auth and sessions

These routes are the entry point for account creation, session establishment, invitation inspection, and invitation acceptance.

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

After registration, verify the email address. Login and invitation acceptance return a session cookie. Password reset confirmation also returns a session cookie after a valid reset.

Use the session for account and workspace routes

Once the cookie is stored, use it for workspace management and token reveal flows.

Registration does not establish browser or cookie-jar state. Login, invitation acceptance, and password reset confirmation do. These session flows are separate from the workspace token flow used by the SDK.

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"}' \
  https://api.radioso.ai/api/v1/auth/register

organizationName is optional. The required fields are email and password.

Registration returns account and default workspace bootstrap data, sends a verification email, and does not set a session cookie. The response includes requiresEmailVerification: true.

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.

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.

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.

Endpoint reference

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

text
GET  /api/v1/auth/registration
POST /api/v1/auth/register
POST /api/v1/auth/login
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.
  • 401 usually means the credentials are wrong, or the invitation accept flow is no longer valid.
  • 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.