Authentication
Current runtime: accounts, favorites and community are unavailable. Provider discovery reports disabled; other identity APIs return the existing private, no-store 503 response. The Rust HTTP implementation is archived. This page preserves its contract for a future JavaScript implementation; configuration alone does not enable it. See the runtime/recovery guide.
Authentication is identity-centered and configuration-dependent. Always start with /auth/providers to see whether the deployment enables accounts, email and each identity provider. A documented provider is not automatically configured; unsupported identity flows remain disabled.
For browser authentication, call /auth/session with same-origin credentials to obtain an HttpOnly session cookie and csrf_token. Send that token as X-CSRF-Token, preserve cookies, and send an exact Origin on mutations. Refresh the session state after login, logout or password reset. These are browser sessions, not third-party inference API keys.
Email registration requires verification; password recovery uses one-time email tokens and enumeration-safe messages. Completing a reset revokes existing sessions. OAuth start returns a browser-bound authorization URL; its callback is managed by the provider redirect, with Apple using form POST where configured. Do not invoke callbacks as an ordinary login REST request.
Examples use placeholders for session cookies, CSRF and email tokens. They do not create accounts. The production sign-in UI remains hidden until enabled by configuration.
On this page
- List supported sign-in methods and configuration availability ·
GET /auth/providers - Read or create an anonymous session and CSRF token ·
GET /auth/session - Request email verification ·
POST /auth/register - Sign in with verified email and password ·
POST /auth/login - Send an enumeration-safe password reset email ·
POST /auth/forgot-password - Consume verification or reset token; reset revokes existing sessions ·
POST /auth/email/complete - Revoke the current session and create an anonymous session ·
POST /auth/logout - Start browser-bound authorization; link=true requires a signed-in account ·
POST /auth/oauth/{provider}/start - Consume one-time OAuth transaction and redirect; POST is Apple form_post only ·
GET /auth/oauth/{provider}/callback - Consume one-time OAuth transaction and redirect; POST is Apple form_post only ·
POST /auth/oauth/{provider}/callback
List supported sign-in methods and configuration availability
GET /api/v1/auth/providers
Availability: account/community configuration must be enabled (except /auth/providers).
Access: public read; no TensorTrace API key.
Parameters
This operation has no path or query parameters.
Request example
curl 'https://tensortrace.net/api/v1/auth/providers'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Private, no-store response. | object |
400 | Invalid input, expired or consumed token | No declared JSON body |
401 | Sign-in required or incorrect credentials | No declared JSON body |
403 | Origin/CSRF failure or username confirmation required | No declared JSON body |
404 | Resource not found | No declared JSON body |
409 | Username or identity conflict | No declared JSON body |
429 | Rate limited; retry later | No declared JSON body |
503 | Account feature or provider/mail configuration unavailable | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"enabled": false,
"email_enabled": false,
"providers": [
{
"id": "google/gemini-2.5-flash",
"name": "Google: Gemini 2.5 Flash",
"enabled": false,
"status": "example"
}
]
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
enabled | boolean | No | |
email_enabled | boolean | No | |
providers | array of object | No |
Read or create an anonymous session and CSRF token
GET /api/v1/auth/session
Availability: account/community configuration must be enabled (except /auth/providers).
Access: public read; no TensorTrace API key.
Parameters
This operation has no path or query parameters.
Request example
curl 'https://tensortrace.net/api/v1/auth/session' \
--cookie-jar 'cookies.txt'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Private, no-store response. | AccountSession |
400 | Invalid input, expired or consumed token | No declared JSON body |
401 | Sign-in required or incorrect credentials | No declared JSON body |
403 | Origin/CSRF failure or username confirmation required | No declared JSON body |
404 | Resource not found | No declared JSON body |
409 | Username or identity conflict | No declared JSON body |
429 | Rate limited; retry later | No declared JSON body |
503 | Account feature or provider/mail configuration unavailable | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"user": {
"id": "00000000-0000-4000-8000-000000000001",
"username": "model_reviewer",
"display_name": "Model Reviewer",
"avatar_url": "example",
"avatar_fallback": "example",
"created_at": "2026-10-05T00:00:00Z",
"email": "reviewer@example.com",
"username_confirmed": false,
"identities": [
"example"
],
"first_name": "Model",
"last_name": "Reviewer"
},
"csrf_token": "SESSION_CSRF_TOKEN"
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
user | Account or null | Yes | |
csrf_token | string | Yes |
Request email verification
POST /api/v1/auth/register
Availability: account/community configuration must be enabled (except /auth/providers).
Access: browser session, session-bound CSRF token and exact Origin. See Authentication.
Parameters
This operation has no path or query parameters.
Request body
Content type: application/json. Required.
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
email | string · email | Yes | Email address used for verification, sign-in or password recovery. |
password | string | Yes | Account password, 10–128 Unicode scalar values. Required when completing a password reset. Min. length: 10; Max. length: 128 |
Request example
curl -X POST 'https://tensortrace.net/api/v1/auth/register' \
--cookie 'cookies.txt' \
-H 'Origin: https://tensortrace.net' \
-H 'X-CSRF-Token: SESSION_CSRF_TOKEN' \
-H 'Content-Type: application/json' \
--data '{"email":"reviewer@example.com","password":"EXAMPLE_PASSWORD_ONLY"}'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Private, no-store response. | object |
400 | Invalid input, expired or consumed token | No declared JSON body |
401 | Sign-in required or incorrect credentials | No declared JSON body |
403 | Origin/CSRF failure or username confirmation required | No declared JSON body |
404 | Resource not found | No declared JSON body |
409 | Username or identity conflict | No declared JSON body |
429 | Rate limited; retry later | No declared JSON body |
503 | Account feature or provider/mail configuration unavailable | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"message": "example"
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
message | string | No |
Sign in with verified email and password
POST /api/v1/auth/login
Availability: account/community configuration must be enabled (except /auth/providers).
Access: browser session, session-bound CSRF token and exact Origin. See Authentication.
Parameters
This operation has no path or query parameters.
Request body
Content type: application/json. Required.
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
email | string · email | Yes | Email address used for verification, sign-in or password recovery. |
password | string | Yes | Account password, 10–128 Unicode scalar values. Required when completing a password reset. Min. length: 10; Max. length: 128 |
Request example
curl -X POST 'https://tensortrace.net/api/v1/auth/login' \
--cookie 'cookies.txt' \
-H 'Origin: https://tensortrace.net' \
-H 'X-CSRF-Token: SESSION_CSRF_TOKEN' \
-H 'Content-Type: application/json' \
--data '{"email":"reviewer@example.com","password":"EXAMPLE_PASSWORD_ONLY"}'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Private, no-store response. | AccountSession |
400 | Invalid input, expired or consumed token | No declared JSON body |
401 | Sign-in required or incorrect credentials | No declared JSON body |
403 | Origin/CSRF failure or username confirmation required | No declared JSON body |
404 | Resource not found | No declared JSON body |
409 | Username or identity conflict | No declared JSON body |
429 | Rate limited; retry later | No declared JSON body |
503 | Account feature or provider/mail configuration unavailable | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"user": {
"id": "00000000-0000-4000-8000-000000000001",
"username": "model_reviewer",
"display_name": "Model Reviewer",
"avatar_url": "example",
"avatar_fallback": "example",
"created_at": "2026-10-05T00:00:00Z",
"email": "reviewer@example.com",
"username_confirmed": false,
"identities": [
"example"
],
"first_name": "Model",
"last_name": "Reviewer"
},
"csrf_token": "SESSION_CSRF_TOKEN"
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
user | Account or null | Yes | |
csrf_token | string | Yes |
Send an enumeration-safe password reset email
POST /api/v1/auth/forgot-password
Availability: account/community configuration must be enabled (except /auth/providers).
Access: browser session, session-bound CSRF token and exact Origin. See Authentication.
Parameters
This operation has no path or query parameters.
Request body
Content type: application/json. Required.
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
email | string · email | Yes | Email address used for verification, sign-in or password recovery. |
Request example
curl -X POST 'https://tensortrace.net/api/v1/auth/forgot-password' \
--cookie 'cookies.txt' \
-H 'Origin: https://tensortrace.net' \
-H 'X-CSRF-Token: SESSION_CSRF_TOKEN' \
-H 'Content-Type: application/json' \
--data '{"email":"reviewer@example.com"}'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Private, no-store response. | object |
400 | Invalid input, expired or consumed token | No declared JSON body |
401 | Sign-in required or incorrect credentials | No declared JSON body |
403 | Origin/CSRF failure or username confirmation required | No declared JSON body |
404 | Resource not found | No declared JSON body |
409 | Username or identity conflict | No declared JSON body |
429 | Rate limited; retry later | No declared JSON body |
503 | Account feature or provider/mail configuration unavailable | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"message": "example"
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
message | string | No |
Consume verification or reset token; reset revokes existing sessions
POST /api/v1/auth/email/complete
Availability: account/community configuration must be enabled (except /auth/providers).
Access: browser session, session-bound CSRF token and exact Origin. See Authentication.
Parameters
This operation has no path or query parameters.
Request body
Content type: application/json. Required.
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
token | string | Yes | One-time email verification or password reset token from the email link. |
password | string | No | Account password, 10–128 Unicode scalar values. Required when completing a password reset. Min. length: 10; Max. length: 128 |
Request example
curl -X POST 'https://tensortrace.net/api/v1/auth/email/complete' \
--cookie 'cookies.txt' \
-H 'Origin: https://tensortrace.net' \
-H 'X-CSRF-Token: SESSION_CSRF_TOKEN' \
-H 'Content-Type: application/json' \
--data '{"token":"ONE_TIME_EMAIL_TOKEN","password":"EXAMPLE_PASSWORD_ONLY"}'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Private, no-store response. | AccountSession |
400 | Invalid input, expired or consumed token | No declared JSON body |
401 | Sign-in required or incorrect credentials | No declared JSON body |
403 | Origin/CSRF failure or username confirmation required | No declared JSON body |
404 | Resource not found | No declared JSON body |
409 | Username or identity conflict | No declared JSON body |
429 | Rate limited; retry later | No declared JSON body |
503 | Account feature or provider/mail configuration unavailable | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"user": {
"id": "00000000-0000-4000-8000-000000000001",
"username": "model_reviewer",
"display_name": "Model Reviewer",
"avatar_url": "example",
"avatar_fallback": "example",
"created_at": "2026-10-05T00:00:00Z",
"email": "reviewer@example.com",
"username_confirmed": false,
"identities": [
"example"
],
"first_name": "Model",
"last_name": "Reviewer"
},
"csrf_token": "SESSION_CSRF_TOKEN"
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
user | Account or null | Yes | |
csrf_token | string | Yes |
Revoke the current session and create an anonymous session
POST /api/v1/auth/logout
Availability: account/community configuration must be enabled (except /auth/providers).
Access: browser session, session-bound CSRF token and exact Origin. See Authentication.
Parameters
This operation has no path or query parameters.
Request example
curl -X POST 'https://tensortrace.net/api/v1/auth/logout' \
--cookie 'cookies.txt' \
-H 'Origin: https://tensortrace.net' \
-H 'X-CSRF-Token: SESSION_CSRF_TOKEN'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Private, no-store response. | AccountSession |
400 | Invalid input, expired or consumed token | No declared JSON body |
401 | Sign-in required or incorrect credentials | No declared JSON body |
403 | Origin/CSRF failure or username confirmation required | No declared JSON body |
404 | Resource not found | No declared JSON body |
409 | Username or identity conflict | No declared JSON body |
429 | Rate limited; retry later | No declared JSON body |
503 | Account feature or provider/mail configuration unavailable | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"user": {
"id": "00000000-0000-4000-8000-000000000001",
"username": "model_reviewer",
"display_name": "Model Reviewer",
"avatar_url": "example",
"avatar_fallback": "example",
"created_at": "2026-10-05T00:00:00Z",
"email": "reviewer@example.com",
"username_confirmed": false,
"identities": [
"example"
],
"first_name": "Model",
"last_name": "Reviewer"
},
"csrf_token": "SESSION_CSRF_TOKEN"
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
user | Account or null | Yes | |
csrf_token | string | Yes |
Start browser-bound authorization; link=true requires a signed-in account
POST /api/v1/auth/oauth/{provider}/start
Availability: account/community configuration must be enabled (except /auth/providers).
Access: browser session, session-bound CSRF token and exact Origin. See Authentication.
Parameters
| Name | Location | Required | Type / limits | Meaning |
|---|---|---|---|---|
provider | path | Yes | string | Identity-provider ID from GET /auth/providers. Only configured providers can start sign-in. |
Request body
Content type: application/json. Required.
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
link | boolean | No | false starts sign-in; true links the identity provider to the current signed-in account. Default: false |
Request example
curl -X POST 'https://tensortrace.net/api/v1/auth/oauth/github/start' \
--cookie 'cookies.txt' \
-H 'Origin: https://tensortrace.net' \
-H 'X-CSRF-Token: SESSION_CSRF_TOKEN' \
-H 'Content-Type: application/json' \
--data '{"link":false}'
Responses
| Status | Meaning | Body type |
|---|---|---|
200 | Private, no-store response. | object |
400 | Invalid input, expired or consumed token | No declared JSON body |
401 | Sign-in required or incorrect credentials | No declared JSON body |
403 | Origin/CSRF failure or username confirmation required | No declared JSON body |
404 | Resource not found | No declared JSON body |
409 | Username or identity conflict | No declared JSON body |
429 | Rate limited; retry later | No declared JSON body |
503 | Account feature or provider/mail configuration unavailable | No declared JSON body |
Response example · 200
Illustrative values; schema-valid and not a live catalog measurement.
{
"url": "https://example.com/model"
}
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
url | string · uri | No |
Consume one-time OAuth transaction and redirect; POST is Apple form_post only
GET /api/v1/auth/oauth/{provider}/callback
Availability: account/community configuration must be enabled (except /auth/providers).
Access: identity-provider callback; managed by the authorization flow.
Parameters
| Name | Location | Required | Type / limits | Meaning |
|---|---|---|---|---|
provider | path | Yes | string | Identity-provider ID from GET /auth/providers. Only configured providers can start sign-in. |
state | query | No | string | One-time, browser-bound OAuth state returned by the identity provider. Managed by the redirect flow. |
code | query | No | string | Temporary authorization code returned by the identity provider; exchanged by the server. |
error | query | No | string | OAuth failure code returned by the identity provider instead of an authorization code. |
Request example
curl 'https://tensortrace.net/api/v1/auth/oauth/github/callback'
Callback values are generated by the OAuth provider. This shape example cannot complete sign-in on its own.
Responses
| Status | Meaning | Body type |
|---|---|---|
303 | Redirect to dashboard or sign-in error page. Requires the browser-bound OAuth transaction cookie. | No declared JSON body |
400 | Invalid input, expired or consumed token | No declared JSON body |
401 | Sign-in required or incorrect credentials | No declared JSON body |
403 | Origin/CSRF failure or username confirmation required | No declared JSON body |
404 | Resource not found | No declared JSON body |
409 | Username or identity conflict | No declared JSON body |
429 | Rate limited; retry later | No declared JSON body |
503 | Account feature or provider/mail configuration unavailable | No declared JSON body |
Redirect response
The callback redirects the browser. Follow the authorization flow instead of expecting a JSON profile.
Consume one-time OAuth transaction and redirect; POST is Apple form_post only
POST /api/v1/auth/oauth/{provider}/callback
Availability: account/community configuration must be enabled (except /auth/providers).
Access: identity-provider callback; managed by the authorization flow.
Parameters
| Name | Location | Required | Type / limits | Meaning |
|---|---|---|---|---|
provider | path | Yes | string | Identity-provider ID from GET /auth/providers. Only configured providers can start sign-in. |
Request body
Content type: application/x-www-form-urlencoded. Required.
| Field | Type | Required | Meaning / constraints |
|---|---|---|---|
state | string | Yes | One-time, browser-bound OAuth state returned by the identity provider. Managed by the redirect flow. |
code | string | No | Temporary authorization code returned by the identity provider; exchanged by the server. |
error | string | No | OAuth failure code returned by the identity provider instead of an authorization code. |
user | string | No | Apple’s JSON-encoded first-consent user profile, when supplied by Apple. |
Request example
curl -X POST 'https://tensortrace.net/api/v1/auth/oauth/github/callback' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'state=OAUTH_STATE' \
--data-urlencode 'code=AUTHORIZATION_CODE'
Callback values are generated by the OAuth provider. This shape example cannot complete sign-in on its own.
Responses
| Status | Meaning | Body type |
|---|---|---|
303 | Redirect to dashboard or sign-in error page. Requires the browser-bound OAuth transaction cookie. | No declared JSON body |
400 | Invalid input, expired or consumed token | No declared JSON body |
401 | Sign-in required or incorrect credentials | No declared JSON body |
403 | Origin/CSRF failure or username confirmation required | No declared JSON body |
404 | Resource not found | No declared JSON body |
409 | Username or identity conflict | No declared JSON body |
429 | Rate limited; retry later | No declared JSON body |
503 | Account feature or provider/mail configuration unavailable | No declared JSON body |
Redirect response
The callback redirects the browser. Follow the authorization flow instead of expecting a JSON profile.