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

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"}' \
  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 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.

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.