Auth
Dashboard sign-in: password, magic link, TOTP.
17 endpoints.
POST /v1/auth/signupPOST /v1/auth/loginPOST /v1/auth/magic-linkPOST /v1/auth/magic-link/verifyPOST /v1/auth/mfa/verifyPOST /v1/auth/logoutGET /v1/auth/mePOST /v1/auth/verify-emailPOST /v1/auth/password/forgotPOST /v1/auth/password/resetPOST /v1/auth/password/changePOST /v1/auth/totp/setupPOST /v1/auth/totp/enablePOST /v1/auth/totp/disableGET /v1/auth/sessionsDELETE /v1/auth/sessions/{session_id}GET /v1/whoami
POST
/v1/auth/signupCreate a user and a store (14-day trial)
No key needed
Request body application/json SignupRequest
| Name | Type | Required | Description |
|---|---|---|---|
email | string (email) | yes | |
name | string | yes | max length 200 |
password | string | null | no | Omit to use magic links.min length 12 · max length 200 |
store_name | string | null | no | The new store's name. Required unless invite_token is given.max length 200 |
locale | "en" | "ar" | no | Dashboard language.default "en" |
invite_token | string | null | no | Sign up from a team invite: join that store (the email must match the invite); no new store.max length 200 |
Responses
- 201Successful Response
LoginResult
POST
/v1/auth/loginEmail + password
No key needed
Request body application/json LoginRequest
| Name | Type | Required | Description |
|---|---|---|---|
email | string (email) | yes | |
password | string | yes | max length 200 |
Responses
- 200Successful Response
LoginResult
POST
/v1/auth/magic-linkEmail a one-time sign-in link (15 minutes)
No key needed
Request body application/json MagicLinkRequest
| Name | Type | Required | Description |
|---|---|---|---|
email | string (email) | yes | |
locale | "en" | "ar" | no | Language of the email.default "en" |
Responses
- 200Successful Response
LoginResult
POST
/v1/auth/magic-link/verifyAuth Magic Link Verify
No key needed
Request body application/json TokenRequest
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes | min length 20 · max length 200 |
Responses
- 200Successful Response
LoginResult
POST
/v1/auth/mfa/verifySecond step: TOTP or recovery code
Needs a key or a dashboard session
Request body application/json MfaVerifyRequest
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | 6-digit TOTP code or a recovery code.pattern ^(\d{6}|[a-z0-9]{10})$ |
Responses
- 200Successful Response
LoginResult
POST
/v1/auth/logoutAuth Logout
Needs a key or a dashboard session
Responses
- 200Successful Response
Accepted
GET
/v1/auth/meAuth Me
Needs a key or a dashboard session
Responses
- 200Successful Response
UserOut
POST
/v1/auth/verify-emailAuth Verify Email
No key needed
Request body application/json TokenRequest
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes | min length 20 · max length 200 |
Responses
- 200Successful Response
Accepted
POST
/v1/auth/password/forgotAuth Password Forgot
No key needed
Request body application/json MagicLinkRequest
| Name | Type | Required | Description |
|---|---|---|---|
email | string (email) | yes | |
locale | "en" | "ar" | no | Language of the email.default "en" |
Responses
- 200Successful Response
Accepted
POST
/v1/auth/password/resetAuth Password Reset
No key needed
Request body application/json PasswordResetRequest
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes | min length 20 · max length 200 |
password | string | yes | min length 12 · max length 200 |
Responses
- 200Successful Response
Accepted
POST
/v1/auth/password/changeChange the password (needs the current one; ends your other sessions)
Needs a key or a dashboard session
Request body application/json PasswordChangeRequest
| Name | Type | Required | Description |
|---|---|---|---|
current_password | string | yes | max length 200 |
new_password | string | yes | min length 12 · max length 200 |
Responses
- 200Successful Response
Accepted
POST
/v1/auth/totp/setupAuth Totp Setup
Needs a key or a dashboard session
Responses
- 200Successful Response
TotpSetup
POST
/v1/auth/totp/enableAuth Totp Enable
Needs a key or a dashboard session
Request body application/json TotpEnableRequest
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | pattern ^\d{6}$ |
Responses
- 200Successful Response
RecoveryCodes
POST
/v1/auth/totp/disableAuth Totp Disable
Needs a key or a dashboard session
Request body application/json MfaVerifyRequest
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | 6-digit TOTP code or a recovery code.pattern ^(\d{6}|[a-z0-9]{10})$ |
Responses
- 200Successful Response
Accepted
GET
/v1/auth/sessionsAuth Sessions List
Needs a key or a dashboard session
Responses
- 200Successful Response
SessionOut[]
DELETE
/v1/auth/sessions/{session_id}Auth Sessions Revoke
Needs a key or a dashboard session
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
session_id | path | string | yes |
Responses
- 200Successful Response
Deleted
GET
/v1/whoamiWho these credentials are (Test connection)
Needs a key or a dashboard session
Responses
- 200Successful Response
WhoAmI
Data shapes on this page
SignupRequest
| Name | Type | Required | Description |
|---|---|---|---|
email | string (email) | yes | |
name | string | yes | max length 200 |
password | string | null | no | Omit to use magic links.min length 12 · max length 200 |
store_name | string | null | no | The new store's name. Required unless invite_token is given.max length 200 |
locale | "en" | "ar" | no | Dashboard language.default "en" |
invite_token | string | null | no | Sign up from a team invite: join that store (the email must match the invite); no new store.max length 200 |
LoginResult
On success the API sets the `sg_session` cookie (HttpOnly, Secure, SameSite=Lax) and returns the CSRF token, which the web app sends back as `X-CSRF-Token` on every write.
| Name | Type | Required | Description |
|---|---|---|---|
status | "ok" | "mfa_required" | "email_sent" | yes | |
user | UserOut | null | no | |
csrf_token | string | null | no | |
weak_password | boolean | no | Password sign-in only: the password is on the breached-password list or no longer meets the rules. Sign-in still works; ask the user to change it (POST /v1/auth/password/change).default false |
UserOut
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
email | string | yes | |
name | string | null | yes | |
locale | "en" | "ar" | yes | |
email_verified | boolean | yes | |
totp_enabled | boolean | yes | |
is_superadmin | boolean | yes | |
memberships | MembershipOut[] | yes |
MembershipOut
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
tenant_id | string | yes | |
tenant_name | string | yes | |
tenant_slug | string | yes | |
role | "owner" | "admin" | "editor" | "viewer" | yes |
LoginRequest
| Name | Type | Required | Description |
|---|---|---|---|
email | string (email) | yes | |
password | string | yes | max length 200 |
MagicLinkRequest
| Name | Type | Required | Description |
|---|---|---|---|
email | string (email) | yes | |
locale | "en" | "ar" | no | Language of the email.default "en" |
TokenRequest
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes | min length 20 · max length 200 |
MfaVerifyRequest
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | 6-digit TOTP code or a recovery code.pattern ^(\d{6}|[a-z0-9]{10})$ |
Accepted
| Name | Type | Required | Description |
|---|---|---|---|
accepted | boolean | no | default true |
job | Job | null | no |
Job
A row of the shared `jobs` table. Poll GET /v1/jobs/{id} until status is terminal.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
kind | "reindex" | "import" | "sync" | "translate_backfill" | "translate_writeback" | "export" | "data_export" | "data_delete" | "embed" | "synonym_mining" | yes | |
status | "queued" | "running" | "succeeded" | "failed" | "canceled" | yes | |
progress | number | no | default 0 · min 0 · max 1 |
created_at | string (date-time) | yes | |
started_at | string (date-time) | null | no | |
finished_at | string (date-time) | null | no | |
result | object | null | no | |
error | string | null | no |
PasswordResetRequest
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes | min length 20 · max length 200 |
password | string | yes | min length 12 · max length 200 |
PasswordChangeRequest
Signed-in password change. The new password follows the sign-up rules (12+ characters, not on the breached-password list, not built from the email or name).
| Name | Type | Required | Description |
|---|---|---|---|
current_password | string | yes | max length 200 |
new_password | string | yes | min length 12 · max length 200 |
TotpSetup
| Name | Type | Required | Description |
|---|---|---|---|
secret | string | yes | |
otpauth_url | string | yes |
TotpEnableRequest
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | pattern ^\d{6}$ |
RecoveryCodes
| Name | Type | Required | Description |
|---|---|---|---|
codes | string[] | yes | Shown once. 10 single-use codes. |
SessionOut
| Name | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
created_at | string (date-time) | yes | |
last_seen_at | string (date-time) | yes | |
user_agent | string | null | yes | |
current | boolean | yes |
Deleted
| Name | Type | Required | Description |
|---|---|---|---|
deleted | boolean | no | default true |
id | string | yes |
WhoAmI
What the current credentials are (connectors use it for 'Test connection').
| Name | Type | Required | Description |
|---|---|---|---|
tenant_id | string | yes | |
auth | "public_key" | "secret_key" | "session" | yes | |
key_id | string | null | no | |
user_id | string | null | no | |
role | "owner" | "admin" | "editor" | "viewer" | null | no | |
scopes | string[] | yes |