Auth
Dashboard accounts and session tokens.
Create an account
POST /v1/auth/signup
The first account on a fresh instance becomes the owner. Afterwards signup follows ONESEND_SIGNUP. Sets the onesend_session HttpOnly cookie for the dashboard and returns the session token for scripts.
Authentication: None.
Request body
| Field | Type | Description |
|---|---|---|
emailrequired | string (email) | |
passwordrequired | string | |
name | string | |
workspaceName | string | |
setupCode | string | The setup code printed by the installer (ONESEND_SETUP_CODE). Needed only for the first account, when the server has one. |
Responses
{
"token": string,
"user": {
"id": string,
"email": string,
"name": string or null
},
"workspace": {
"id": string,
"name": string,
"slug": string,
"plan": string
}
}Errors: 400, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Sign in
POST /v1/auth/login
Sets the onesend_session HttpOnly cookie for the dashboard and returns the session token for scripts. Rate limited per client and per account. Accounts with two-factor authentication get 401 mfa_required with error.details.mfaToken; finish with POST /v1/auth/login/2fa.
Authentication: None.
Request body
| Field | Type | Description |
|---|---|---|
emailrequired | string (email) | |
passwordrequired | string |
Responses
{
"token": string,
"user": {
"id": string,
"email": string,
"name": string or null
},
"workspace": {
"id": string,
"name": string,
"slug": string,
"plan": string
}
}Errors: 400, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Sign out (revoke the session and clear the cookie)
POST /v1/auth/logout
Authentication: None.
Responses
Errors: 400, 404, 409, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Current user, workspace and credentials
GET /v1/auth/me
Authentication: Authorization: Bearer with an API key or a session token.
Responses
{
"user": {
"id": string,
"email": string,
"name": string or null
},
"workspace": {
"id": string,
"name": string,
"slug": string,
"plan": string,
"settings": object
},
"workspaces": [{
"id": string,
"name": string,
"role": string
}],
"auth": {
"kind": "session" | "api_key",
"scope": string,
"mode": string
},
"role": string or null,
"twoFactor": {
"enabled": boolean,
"required": boolean,
"blocked": boolean
},
"capabilities": {
"edition": "self_hosted" | "cloud" | "desktop",
"inbox": boolean,
"connectedAccounts": boolean,
"encryptMail": boolean,
"cloudLink": {
"linked": boolean,
"url": string,
"workspaceName": string
},
"license": {
"required": boolean,
"active": boolean
},
"plansEnabled": boolean
}
}Errors: 400, 401, 403, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Switch the current workspace
POST /v1/auth/workspace
Sessions only. Later requests with this session act in the chosen workspace (the dashboard workspace switcher). Scripts can also send X-Workspace-Id per request. API keys always belong to one workspace.
Authentication: Authorization: Bearer with an API key or a session token.
Request body
| Field | Type | Description |
|---|---|---|
workspaceIdrequired | string |
Responses
{
"workspace": {
"id": string,
"name": string,
"slug": string,
"plan": string
},
"role": string
}Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.401Missing credentials (unauthorized), an unknown or revoked API key (invalid_api_key) or an expired session (invalid_session). Typeunauthorized.403The API key's permission does not allow this operation (insufficient_scope; configuration needs anadminkey), a test key was used outside its sandbox (test_key_not_allowed), a Conversion tracking key was used (publishable_key), or a cookie request is missingX-OneSend-Client: dashboard(csrf_header_required). Typeforbidden.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Sign in: second step
POST /v1/auth/login/2fa
When the account has two-factor authentication, sign-in answers 401 mfa_required with error.details.mfaToken; send it here with the code from the authenticator app or a recovery code. The challenge is valid for 5 minutes.
Authentication: None.
Request body
| Field | Type | Description |
|---|---|---|
mfaTokenrequired | string | |
code | string | |
recoveryCode | string |
Responses
{
"token": string,
"user": {
"id": string,
"email": string,
"name": string or null
},
"workspace": {
"id": string,
"name": string,
"slug": string,
"plan": string
},
"recoveryCodesRemaining": number
}Errors: 400, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Request a password reset link
POST /v1/auth/password/forgot
Always answers 202 with the same message and timing, whether or not the email has an account. The email is sent through the router of a workspace the account belongs to. If the server cannot deliver email (only the sandbox provider), an administrator can create a link on the server: npm run admin -- reset-password <email>.
Authentication: None.
Request body
| Field | Type | Description |
|---|---|---|
emailrequired | string (email) |
Responses
{
"ok": true,
"message": string
}Errors: 400, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Check a password reset link
POST /v1/auth/password/check
Tells the reset page whether the link can still be used (and whether a two-factor code will be needed). Does not use the link.
Authentication: None.
Request body
| Field | Type | Description |
|---|---|---|
tokenrequired | string |
Responses
{
"valid": boolean,
"twoFactor": boolean
}Errors: 400, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
Set a new password with a reset link
POST /v1/auth/password/reset
The link works once, for 30 minutes, and stops working if the password changes in the meantime. Every session of the account is signed out. Accounts with two-factor authentication also need a code (or a recovery code). Does not sign in: sign in with the new password afterwards.
Authentication: None.
Request body
| Field | Type | Description |
|---|---|---|
tokenrequired | string | |
passwordrequired | string | |
code | string | Two-factor code or recovery code, when the account has two-factor authentication |
Responses
{
"ok": true
}Errors: 400, 404, 409, 413, 415, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.404The resource does not exist in this workspace (not_found)409The request conflicts with the current state, for example a duplicate name or a reusedIdempotency-Key(conflict)413The request body is larger than the limit for this endpoint (payload_too_large)415The body is not sent asContent-Type: application/json(unsupported_media_type)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)
First-run status
GET /v1/setup/status
Whether this instance has an account yet, and how sign-up works. No authentication. The database kind is shown only until the first account exists; paths, hosts and secrets are never returned.
Authentication: None.
Responses
{
"hasUsers": boolean,
"databaseKind": "sqlite" | "postgres" | "libsql" | "pglite" | "d1" | null,
"dataDirIsDefault": boolean or null,
"publicUrl": string,
"signupMode": "open" | "first-user" | "invite" | "closed",
"signupAllowed": boolean,
"setupCodeRequired": boolean
}Errors: 400, 404, 429, 500
400Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (invalid_json) or the pagination cursor is not valid (invalid_cursor). Typeinvalid_request.404The resource does not exist in this workspace (not_found)429Too many requests; retry after the time in theRetry-Afterheader (rate_limited)500Unexpected server error (internal)