API Reference
Manage auth sessions and account identity routes
This page is the source of truth for the public auth surface and the signed in account routes that depend on session identity.
Machine readable coverage for the customer account subset lives in /docs/account. This page stays broader: it explains session behavior, bearer plus cookie flows, and related public token driven account recovery or confirmation patterns that are easier to understand narratively than in OpenAPI.
Auth model
Signed in account routes
Authorization: Bearer ACCESS_TOKEN
Browser clients keep the access token in memory and send it as a bearer header for profile routes, GDPR export requests, and account actions.
Session continuation
secure httpOnly refresh cookie
Refresh rotates the session from the SolidRelay-refresh-token cookie and returns a new bearer access token in the response body.
Public entry and recovery routes
no bearer token required
Login, verification, password recovery, and MFA completion are public flows.
Token Lifecycle Routes
Use these routes to start, rotate, and end a signed in session
The token lifecycle starts with sign in, continues through refresh, and ends with logout. The contracts below focus on the routes external clients can integrate directly.
Register
POST/auth/register
Request
Register is a public JSON route for creating a new account and starting the initial hybrid session.
Content-Type
required header: application/json
Registration expects a JSON request body.
required email, max 255
Email address for the new account. Values are trimmed and lowercased.
password
required strong password, 8-128
Password must satisfy the platform strong-password policy.
captchaToken
optional string
Required when CAPTCHA enforcement is enabled for registration; omit it only when CAPTCHA is disabled for the environment.
Response
Successful registration returns an access token in the response body, sets the refresh cookie, and may return challenge fields when verification or MFA is required.
accessToken
string
Bearer access token for authenticated account routes. Browser clients should keep it in memory only.
Set-Cookie: SolidRelay-refresh-token
secure httpOnly cookie
Session continuation cookie used by the refresh endpoint.
tokenType
Bearer
Authorization scheme for the access token.
accessExpiresIn
string
Lifetime for the returned access token.
refreshExpiresIn
string
Lifetime for the refresh token or secure refresh-cookie session.
user
object
Signed-in account identity returned with the session.
Login
POST/auth/login
Request
Login is a public JSON route. It accepts email and password credentials. Include an anti-abuse token only after repeated failed attempts trigger CAPTCHA enforcement for the email or IP.
Content-Type
required header: application/json
Login expects a JSON request body.
required email, max 255
Email address for the account attempting to sign in.
password
required string, 8-128
Account password for the email being authenticated.
captchaToken
optional string
Required only after suspicious login activity triggers CAPTCHA enforcement.
Response
A successful login returns an access token and sets the refresh cookie. Challenge flows can instead return verification or MFA fields that the client must complete before the session is fully active.
accessToken
string
Bearer access token for authenticated account routes. Browser clients should keep it in memory only.
Set-Cookie: SolidRelay-refresh-token
secure httpOnly cookie
Session continuation cookie used by the refresh endpoint.
tokenType
Bearer
Authorization scheme for the access token.
accessExpiresIn
string
Lifetime for the returned access token.
refreshExpiresIn
string
Lifetime for the refresh token or secure refresh-cookie session.
user
object
Signed-in account identity returned with the session.
user.id
string
Identifier for the signed in account.
user.email
string
Email address for the signed in account.
user.role
string
Role assigned to the signed in account.
requiresEmailVerification
boolean
Signals that the client must complete email verification before the signed in session becomes active.
verificationToken
string
Challenge token used with the email-verification completion route.
verificationExpiresIn
string
Lifetime for the verification challenge when login requires email confirmation.
requiresTotp
boolean
Signals that the client must finish TOTP MFA before the session is complete.
mfaToken
string
Short-lived challenge token consumed by the MFA completion route.
mfaTokenExpiresIn
string
Lifetime for the MFA challenge token when a second factor is required.
requiresTotpSetup
boolean
Signals that the user must complete initial TOTP setup before the session is fully active.
totpSecret
string
Shared secret for the initial TOTP setup flow when setup is required.
totpIssuer
string
Issuer value for the authenticator setup flow.
totpAccountName
string
Account label for the authenticator app entry when setup is required.
totpOtpAuthUrl
string
Provisioning URI for generating a QR code or deep link into an authenticator app.
Google login
POST/auth/google
Request
Google login is a public JSON route that exchanges a Google identity token for the same auth session shape used by login. Accounts keep the exclusive sign-in method with which they were created; matching email addresses are never linked automatically.
Content-Type
required header: application/json
Google login expects a JSON request body.
idToken
required string, 20-4096
Google-issued ID token proving the user identity.
Response
The response follows the shared hybrid session contract and may include verification or MFA challenge fields when additional steps are required.
accessToken
string
Bearer access token for authenticated account routes. Browser clients should keep it in memory only.
Set-Cookie: SolidRelay-refresh-token
secure httpOnly cookie
Session continuation cookie used by the refresh endpoint.
tokenType
Bearer
Authorization scheme for the access token.
user
object
Signed-in account identity returned with the session.
Refresh
POST/auth/refresh
Request
Refresh is a public cookie-backed route. It continues the session from the secure refresh cookie and does not accept a refresh token in the request body.
Request body
no body required
Clients can send an empty POST body. Refresh uses the secure cookie for session continuation.
SolidRelay-refresh-token
required secure cookie
Cookie-backed refresh session used by browser flows that rely on httpOnly storage.
Response
Refresh rotates the cookie-backed session and returns a new bearer access token plus the same metadata shape as login when the cookie is valid.
accessToken
string
Replacement bearer access token for authenticated account routes. Browser clients should keep it in memory only.
Set-Cookie: SolidRelay-refresh-token
secure httpOnly cookie
Rotated refresh-session cookie used for the next refresh call.
tokenType
Bearer
Authorization scheme for the returned access token.
accessExpiresIn
string
Lifetime for the returned access token.
refreshExpiresIn
string
Lifetime for the refreshed session token or rotated cookie.
user
object
Signed-in account identity for the continued session.
user.id
string
Identifier for the signed in account.
user.email
string
Email address for the signed in account.
user.role
string
Role assigned to the signed in account.
Logout
POST/auth/logout
Request
Logout is public in the sense that it does not require a valid session header, but it only has effect when the request carries the refresh session that should be revoked.
Authorization
optional bearer header
Bearer access token that helps identify the active session context for full logout and audit handling.
SolidRelay-refresh-token
optional secure cookie
Cookie-backed refresh session to clear and revoke.
Response
Logout returns a simple success payload after clearing the refresh-cookie session and revoking stored state.
success
boolean
Signals that the logout flow completed without error.
Verification And Recovery Routes
Use these flows when sign in is gated by verification or when a user needs account recovery
Verification and recovery begin from a challenge token or signed recovery token and either complete account setup or restore access.
Verify email code
POST/auth/email-verification/verify
Request
Verification is a public JSON route. It consumes the pending verification challenge that was issued by login or another externally initiated verification flow.
Content-Type
required header: application/json
Verification expects a JSON request body.
verificationToken
required string, max 4096
Challenge token for the pending verification flow.
code
required string, 6 digits
Six-digit verification code delivered to the user by email.
Response
Successful verification returns the same hybrid auth response shape as a completed login.
accessToken
string
Bearer access token for the newly verified session. Browser clients should keep it in memory only.
Set-Cookie: SolidRelay-refresh-token
secure httpOnly cookie
Session continuation cookie used by the refresh endpoint.
tokenType
Bearer
Authorization scheme for the returned access token.
user
object
Signed-in account identity returned with the completed verification flow.
user.id
string
Identifier for the newly verified account.
user.email
string
Primary email address that just completed verification.
user.role
string
Role assigned to the verified account.
Resend email code
POST/auth/email-verification/resend
Request
Resend verification is a public JSON route that extends a pending email-verification challenge.
Content-Type
required header: application/json
Resend expects a JSON request body.
verificationToken
required string, max 4096
Existing verification challenge token that should receive a fresh code.
Response
Resend returns the auth challenge shape again so the client can continue the verification flow with the refreshed token window.
requiresEmailVerification
boolean
Signals that the account is still pending verification.
verificationToken
string
Challenge token that remains valid for the next verify attempt.
verificationExpiresIn
string
Lifetime for the refreshed verification challenge.
message
string
Human-readable message confirming that a new verification code was sent.
Request password reset
POST/auth/password-reset/request
Request
Password reset request is a public JSON route that starts recovery without revealing whether the email exists.
Content-Type
required header: application/json
Reset request expects a JSON request body.
required email, max 255
Email address for the account requesting password recovery.
Response
Reset request always returns success so clients do not leak account-existence checks through the UI.
success
boolean
Signals that the reset-request workflow completed without error.
Verify reset token
POST/auth/password-reset/verify
Request
Token verification is a public JSON route that checks whether a recovery token can still be used.
Content-Type
required header: application/json
Reset-token verification expects a JSON request body.
token
required string, max 4096
Signed reset token from the password-recovery email.
Response
Verification returns only whether the token is currently valid.
valid
boolean
Signals whether the reset token can still be used for confirmation.
Confirm password reset
POST/auth/password-reset/confirm
Request
Password reset confirmation is a public JSON route. It uses a signed reset token plus the user's new password.
Content-Type
required header: application/json
Reset confirmation expects a JSON request body.
token
required string, max 4096
Signed reset token from the password-recovery email.
password
required strong password
Replacement password that satisfies the platform's password policy.
Response
Confirmation returns a simple success payload after saving the new password and invalidating stored refresh sessions.
success
boolean
Signals that the password reset completed without error.
MFA Completion
Complete public TOTP sign in only when the primary auth step returned an MFA challenge
Use this route only when a previous auth response returned requiresTotp and a temporary mfaToken.
POST/auth/mfa/totp/complete
Request
MFA completion is a public JSON route that finishes a previously challenged sign in.
Content-Type
required header: application/json
MFA completion expects a JSON request body.
mfaToken
required string
Temporary challenge token returned by the primary auth step.
totpCode
required string
Six digit authenticator code for completion or initial setup.
Response
When successful, MFA completion returns the standard hybrid auth response for the signed in session.
accessToken
string
Bearer access token for the completed session. Browser clients should keep it in memory only.
Set-Cookie: SolidRelay-refresh-token
secure httpOnly cookie
Session continuation cookie used by the refresh endpoint.
tokenType
Bearer
Authorization scheme for the returned access token.
user
object
Signed-in account identity returned with the completed session.
user.id
string
Identifier for the account that completed the MFA step.
user.email
string
Email address for the account that completed the MFA step.
user.role
string
Role assigned to the completed signed in session.
Account And Profile Routes
Use bearer auth to inspect the signed in session and manage profile data
Use the session route for auth context and the profile routes for stable account fields like name, email, and role.
Session auth profile
GET/auth/me
Request
This route reads the validated bearer session and returns auth-context fields for the current access token.
Authorization
required bearer header
Use a valid access token for the signed in session.
Response
The response describes the authenticated session, not the broader editable user profile.
id
string
Identifier for the authenticated user.
role
string
Effective role for the authenticated session.
status
string
Current account status for the authenticated user.
superAdminAuthorized
boolean
Signals whether elevated authorization is active for the current session.
impersonating
boolean
Signals whether the session is impersonating another user.
impersonationReadOnly
boolean
Signals whether the impersonation session is restricted to read-only access.
impersonationExpiresAt
ISO 8601 datetime or null
Expiration time for the impersonation session when one is active.
impersonatedByUserId
string or null
Identifier for the original operator when the session is running under impersonation.
User profile
GET/user/profile
Request
Profile read uses the signed in bearer identity and does not take a request body.
Authorization
required bearer header
Use a valid access token for the account whose profile should be read.
Response
Profile read returns the stable account fields most clients show in account settings.
id
string
Identifier for the user profile.
string
Email address for the signed in account.
role
string
Current role assigned to the account.
firstName
string or null
Saved first name for the account when present.
lastName
string or null
Saved last name for the account when present.
createdAt
ISO 8601 datetime
Timestamp for when the account was created.
credentialState
known or unknown
Whether the server can identify exactly one valid credential attached to the account. Missing, malformed, or multiple credentials fail closed for credential-management actions.
signInMethods
array
The public label and email for the account's exclusive password or federated sign-in method, returned as an array with at most one item. Provider subjects and credential secrets are never returned.
capabilities
object
Server-derived booleans indicating whether Solid Relay permits password and local login-email changes.
Update profile
PATCH/user/profile
Request
Profile updates use bearer auth and a small JSON body for editable name fields.
Authorization
required bearer header
Use a valid access token for the profile being updated.
Content-Type
required header: application/json
Profile update expects a JSON request body.
firstName
optional string, 1-100
Trimmed first name. HTML and control characters are rejected.
lastName
optional string, 1-100
Trimmed last name. HTML and control characters are rejected.
Response
Profile update returns the saved profile object after validation and persistence succeed.
id
string
Identifier for the updated user profile.
string
Email address for the signed in account.
role
string
Current role assigned to the account.
firstName
string or null
Saved first name after the update.
lastName
string or null
Saved last name after the update.
createdAt
ISO 8601 datetime
Original account creation timestamp returned with the profile object.
GDPR, Export, And Delete Routes
Use signed in GDPR routes to export account data or delete the current account
Public account flows support two export patterns: immediate bearer authenticated export for direct API clients, and a signed link email flow when the user should download from an inbox based confirmation step.
Immediate export
GET/user/gdpr/export
Request
Immediate export reads the full GDPR export payload for the signed in account in a single bearer authenticated request.
Authorization
required bearer header
Use a valid access token for the account requesting its export data.
Response
The export payload groups the signed in account's stored data by domain so the client can inspect or archive it.
user
object
Core user record for the signed in account.
user.id
string
Identifier for the exported account record.
user.email
string
Primary email address stored on the exported account.
user.role
string
Role recorded for the exported account.
apiKeys
array
API key records owned by the user.
usageLogs
array
Usage-log records associated with the account.
usageMonths
array
Monthly usage summary records for the account.
auditLogs
array
Audit-log entries associated with the account.
subscription
object or null
Subscription state for the account when billing is active.
Email export request
POST/user/gdpr/export-request
Request
This bearer route starts the signed link export flow by emailing a temporary GDPR download link to the account email address.
Authorization
required bearer header
Use a valid access token for the account requesting export delivery by email.
Body
no request body
The API uses the authenticated user identity and does not require additional fields.
Response
The route returns a success acknowledgment after queuing the export-email workflow.
success
boolean
Signals that the email export request flow was accepted.
Delete account
DELETE/user/gdpr
Request
Account deletion is a destructive bearer authenticated route for the currently signed in account.
Authorization
required bearer header
Use a valid access token for the account that should be deleted.
Response
Deletion returns a simple success payload after the account-removal workflow has started successfully.
success
boolean
Signals that the delete-account flow completed without error.
Next Steps
Use concepts for the mental model and API keys for the rendering credential surface
Most auth confusion comes from mixing bearer identity with rendering credentials.