Authentication
User authentication, sessions, and API keys
32 endpoints
Register a new user
Request BodyRegisterRequest
emailrequiredstringemailpasswordrequiredstringResponses
Response fields
dataobjectmessagestring/api/v1/auth/registercurl -X POST "https://api.uluops.ai/api/v1/auth/register" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePass123!"
}'{
"data": {
"user": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "user@example.com",
"role": "user",
"subscriptionTier": "free",
"username": "...",
"name": "...",
"bio": "...",
"timezone": "...",
"websiteUrl": "...",
"avatarUrl": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z",
"deletedAt": "2026-01-15T10:30:00Z",
"isActive": true,
"hasAvatar": true,
"usernameConfirmed": true
},
"sessionToken": "...",
"expiresAt": "2026-01-15T10:30:00Z"
},
"message": "..."
}Login with email and password
Request BodyLoginRequest
emailrequiredstringemailpasswordrequiredstringResponses
Response fields
dataobject/api/v1/auth/logincurl -X POST "https://api.uluops.ai/api/v1/auth/login" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "SecurePass123!"
}'{
"data": {
"user": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "user@example.com",
"role": "user",
"subscriptionTier": "free",
"username": "...",
"name": "...",
"bio": "...",
"timezone": "...",
"websiteUrl": "...",
"avatarUrl": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z",
"deletedAt": "2026-01-15T10:30:00Z",
"isActive": true,
"hasAvatar": true,
"usernameConfirmed": true
},
"sessionToken": "..."
}
}Begin OAuth social sign-in (plain-anchor entry, direct 302 to the provider)
oauth-social-signin-spec v0.2.3 §4.1. Sets the `oauth_state` cookie (httpOnly, SameSite=Lax, Max-Age=600, Path=/api/v1/auth/oauth) and 302s to the provider's consent screen. A provider whose credentials are not configured is disabled and 404s (feature-flag-off, §13.5). `intent=link` requires an authenticated session and binds the link to the session user.
Parameters
providerrequiredstringpathgooglegithuboriginrequiredstringqueryInitiating frontend origin. Exact-matched against OAUTH_ALLOWED_ORIGINS.
returnTostringqueryPost-login path. Must start with '/'; '//' and URL schemes are rejected (sanitized to '/').
intentstringquerysigninlinksigninResponses
/api/v1/auth/oauth/{provider}/authorizecurl -X GET "https://api.uluops.ai/api/v1/auth/oauth/google/authorize?origin=example-value"OAuth provider callback (302-only boundary — never responds JSON)
oauth-social-signin-spec v0.2.3 §4.2. The browser arrives mid-redirect from the provider, so EVERY outcome is a 302 — including rate limiting and internal errors: - Session: `{origin}{returnTo}` + `session_token` cookie on `.uluops.ai` - MFA required: `{origin}/signin?mfa_challenge={token}&mfa_methods={csv}&expires_at={iso}` (the challenge completes via the existing TOTP/WebAuthn/recovery verify endpoints) - Error: `{origin}/signin?error=oauth_failed&reason={code}` — or `{AUTH_FRONTEND_URL}/signin?error=…` when the state token cannot be trusted. `intent=link` errors land on `{origin}/settings/security` instead. Reason codes (the complete frontend error contract): `state_mismatch` (tampered/expired/nonce-mismatch state — retry sign-in), `provider_error` (user denied at consent screen, or internal error), `exchange_failed` (provider token exchange/profile fetch failed), `email_not_verified` (provider has not verified the email), `account_locked`, `account_deactivated`, `linking_conflict` (identity already linked to another account), `rate_limited` (over 30/min sustained or 5/sec burst per IP).
Parameters
providerrequiredstringpathgooglegithubcodestringqueryAuthorization code from the provider. Absent on user denial → provider_error redirect.
statestringquerySigned state token minted at authorize time.
Responses
/api/v1/auth/oauth/{provider}/callbackcurl -X GET "https://api.uluops.ai/api/v1/auth/oauth/google/callback"List the current user's linked OAuth providers
oauth-social-signin-spec v0.2.3 §4.6 (Phase 3b). Feeds the settings "connected accounts" surface. `providerLogin` is the D-7 snapshot of the provider's username (GitHub only; null for Google).
Responses
Response fields
dataLinkedProvider[]/api/v1/auth/oauth/providerscurl -X GET "https://api.uluops.ai/api/v1/auth/oauth/providers" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": [
{
"provider": "google",
"providerEmail": "...",
"providerName": "...",
"providerLogin": "...",
"lastUsedAt": "2026-01-15T10:30:00Z",
"createdAt": "2026-01-15T10:30:00Z"
}
]
}Unlink (disconnect) an OAuth provider from the current user
oauth-social-signin-spec v0.2.3 §4.6 (Phase 3b). Guarded by the last-auth-method rule — removing the link must leave at least one way to sign in (another provider link or a password credentials row), otherwise the request 409s with code `LAST_AUTH_METHOD`. Unlinking works even for providers whose credentials are currently unconfigured (disabled providers can still be disconnected).
Parameters
providerrequiredstringpathgooglegithubResponses
Response fields
dataobject/api/v1/auth/oauth/{provider}curl -X DELETE "https://api.uluops.ai/api/v1/auth/oauth/google" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"removed": true
}
}Request password reset email
Request BodyForgotPasswordRequest
emailrequiredstringemailResponses
Response fields
messagestring/api/v1/auth/forgot-passwordcurl -X POST "https://api.uluops.ai/api/v1/auth/forgot-password" \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com"
}'{
"message": "..."
}Reset password with token
Also the "set a first password" path for OAuth-only accounts (oauth-social-signin-spec v0.2.3 §7.4, Phase 3a): if the user has no credentials row (signed up via social sign-in), a valid reset token CREATES one instead of silently no-opping. The request leg (/auth/forgot-password) likewise issues tokens for credential-less users, preserving the anti-enumeration response shape.
Request BodyResetPasswordRequest
tokenrequiredstringpasswordrequiredstringResponses
Response fields
messagestring/api/v1/auth/reset-passwordcurl -X POST "https://api.uluops.ai/api/v1/auth/reset-password" \
-H "Content-Type: application/json" \
-d '{
"token": "reset-token-abc123",
"password": "SecurePass123!"
}'{
"message": "..."
}Logout current session
Responses
Response fields
messagestring/api/v1/auth/logoutcurl -X POST "https://api.uluops.ai/api/v1/auth/logout" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"message": "..."
}Logout from all sessions
Responses
Response fields
messagestring/api/v1/auth/logout-allcurl -X POST "https://api.uluops.ai/api/v1/auth/logout-all" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"message": "..."
}List current user's sessions
Responses
Response fields
dataSession[]/api/v1/auth/sessionscurl -X GET "https://api.uluops.ai/api/v1/auth/sessions" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"userId": "550e8400-e29b-41d4-a716-446655440000",
"userAgent": "...",
"ipAddress": "...",
"expiresAt": "2026-01-15T10:30:00Z",
"createdAt": "2026-01-15T10:30:00Z"
}
]
}Delete a specific session
Parameters
idrequiredstringuuidpathSession UUID
Responses
/api/v1/auth/sessions/{id}curl -X DELETE "https://api.uluops.ai/api/v1/auth/sessions/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer $ULUOPS_TOKEN"Set password (for users without password)
Request BodySetPasswordRequest
passwordrequiredstringResponses
Response fields
messagestring/api/v1/auth/passwordcurl -X POST "https://api.uluops.ai/api/v1/auth/password" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"password": "SecurePass123!"
}'{
"message": "..."
}Change password (requires current password)
Request BodyChangePasswordRequest
currentPasswordrequiredstringnewPasswordrequiredstringResponses
Response fields
messagestring/api/v1/auth/passwordcurl -X PUT "https://api.uluops.ai/api/v1/auth/password" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"currentPassword": "SecurePass123!",
"newPassword": "SecurePass123!"
}'{
"message": "..."
}Get current user info
Responses
Response fields
dataobject/api/v1/auth/mecurl -X GET "https://api.uluops.ai/api/v1/auth/me" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": "..."
}Get current user profile
Responses
Response fields
dataobject/api/v1/auth/profilecurl -X GET "https://api.uluops.ai/api/v1/auth/profile" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"user": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "user@example.com",
"role": "user",
"subscriptionTier": "free",
"username": "...",
"name": "...",
"bio": "...",
"timezone": "...",
"websiteUrl": "...",
"avatarUrl": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z",
"deletedAt": "2026-01-15T10:30:00Z",
"isActive": true,
"hasAvatar": true,
"usernameConfirmed": true
}
}
}Update profile
Request BodyUpdateProfileRequest
usernamestring^[a-z][a-z0-9_]{2,29}$namestringbiostringtimezonestring^[A-Za-z_]+/[A-Za-z_]+$websiteUrlstringavatarstringBase64-encoded image (max 500KB)
avatarMimeTypestringimage/pngimage/jpegimage/gifimage/webpResponses
Response fields
dataobjectmessagestring/api/v1/auth/profilecurl -X PATCH "https://api.uluops.ai/api/v1/auth/profile" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'{
"data": {
"user": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "user@example.com",
"role": "user",
"subscriptionTier": "free",
"username": "...",
"name": "...",
"bio": "...",
"timezone": "...",
"websiteUrl": "...",
"avatarUrl": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z",
"deletedAt": "2026-01-15T10:30:00Z",
"isActive": true,
"hasAvatar": true,
"usernameConfirmed": true
}
},
"message": "..."
}Confirm username (one-time)
Sets and confirms the user's username. Required before publishing to registry.
Request Body
usernamerequiredstringResponses
Response fields
dataobject/api/v1/auth/usernamecurl -X PATCH "https://api.uluops.ai/api/v1/auth/username" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"username": "developer1"
}'{
"data": {
"username": "...",
"confirmed": true,
"personalOrgSlug": "..."
}
}Check username availability
Parameters
usernamerequiredstringpathResponses
Response fields
dataobject/api/v1/auth/check-username/{username}curl -X GET "https://api.uluops.ai/api/v1/auth/check-username/developer1"{
"data": {
"available": true,
"reason": "reserved"
}
}Get current user's avatar
Returns the avatar image for the authenticated user. Returns 404 if no avatar is set.
Responses
/api/v1/auth/avatarcurl -X GET "https://api.uluops.ai/api/v1/auth/avatar" \
-H "Authorization: Bearer $ULUOPS_TOKEN"Delete current user's avatar
Removes the avatar for the authenticated user.
Responses
/api/v1/auth/avatarcurl -X DELETE "https://api.uluops.ai/api/v1/auth/avatar" \
-H "Authorization: Bearer $ULUOPS_TOKEN"List API keys
Responses
Response fields
dataApiKey[]countintegerTotal number of API keys
/api/v1/auth/keyscurl -X GET "https://api.uluops.ai/api/v1/auth/keys" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "...",
"lastUsedAt": "2026-01-15T10:30:00Z",
"expiresAt": "2026-01-15T10:30:00Z",
"createdAt": "2026-01-15T10:30:00Z"
}
],
"count": 0
}Create API key
Request BodyCreateApiKeyRequest
namestringexpiresAtstringdate-timeResponses
Response fields
dataobject/api/v1/auth/keyscurl -X POST "https://api.uluops.ai/api/v1/auth/keys" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'{
"data": {
"key": "...",
"apiKey": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "...",
"lastUsedAt": "2026-01-15T10:30:00Z",
"expiresAt": "2026-01-15T10:30:00Z",
"createdAt": "2026-01-15T10:30:00Z"
}
}
}Delete API key
Parameters
idrequiredstringuuidpathAPI Key UUID
Responses
/api/v1/auth/keys/{id}curl -X DELETE "https://api.uluops.ai/api/v1/auth/keys/550e8400-e29b-41d4-a716-446655440000" \
-H "Authorization: Bearer $ULUOPS_TOKEN"Generate TOTP secret and QR URI
Responses
Response fields
dataobject/api/v1/auth/totp/setupcurl -X POST "https://api.uluops.ai/api/v1/auth/totp/setup" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"secret": "...",
"otpauth_uri": "..."
}
}Verify TOTP code to enable TOTP
Request Body
coderequiredstring6-digit TOTP code
Pattern:^\d{6}$Responses
Response fields
messagestring/api/v1/auth/totp/verifycurl -X POST "https://api.uluops.ai/api/v1/auth/totp/verify" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"code": "example-value"
}'{
"message": "..."
}Verify TOTP code during MFA login
Request Body
mfa_challenge_tokenrequiredstringcoderequiredstring^\d{6}$rememberMebooleanfalseResponses
Response fields
dataobject/api/v1/auth/totp/logincurl -X POST "https://api.uluops.ai/api/v1/auth/totp/login" \
-H "Content-Type: application/json" \
-d '{
"mfa_challenge_token": "reset-token-abc123",
"code": "example-value"
}'{
"data": {
"user": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "user@example.com",
"role": "user",
"subscriptionTier": "free",
"username": "...",
"name": "...",
"bio": "...",
"timezone": "...",
"websiteUrl": "...",
"avatarUrl": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z",
"deletedAt": "2026-01-15T10:30:00Z",
"isActive": true,
"hasAvatar": true,
"usernameConfirmed": true
},
"sessionToken": "...",
"expiresAt": "2026-01-15T10:30:00Z"
}
}Disable TOTP (requires password)
Request Body
passwordrequiredstringResponses
Response fields
messagestring/api/v1/auth/totpcurl -X DELETE "https://api.uluops.ai/api/v1/auth/totp" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"password": "SecurePass123!"
}'{
"message": "..."
}Generate new recovery codes
Replaces any existing codes. Requires at least one MFA method enabled.
Responses
Response fields
dataobject/api/v1/auth/recovery-codes/generatecurl -X POST "https://api.uluops.ai/api/v1/auth/recovery-codes/generate" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"codes": [],
"count": 0
}
}Get remaining recovery code count
Responses
Response fields
dataobject/api/v1/auth/recovery-codes/statuscurl -X GET "https://api.uluops.ai/api/v1/auth/recovery-codes/status" \
-H "Authorization: Bearer $ULUOPS_TOKEN"{
"data": {
"remaining": 0,
"total": 0
}
}Regenerate recovery codes (requires password)
Request Body
passwordrequiredstringResponses
Response fields
dataobject/api/v1/auth/recovery-codes/regeneratecurl -X POST "https://api.uluops.ai/api/v1/auth/recovery-codes/regenerate" \
-H "Authorization: Bearer $ULUOPS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"password": "SecurePass123!"
}'{
"data": {
"codes": [],
"count": 0
}
}Verify recovery code during MFA login
Request Body
mfa_challenge_tokenrequiredstringcoderequiredstringrememberMebooleanfalseResponses
Response fields
dataobject/api/v1/auth/recovery-codes/verifycurl -X POST "https://api.uluops.ai/api/v1/auth/recovery-codes/verify" \
-H "Content-Type: application/json" \
-d '{
"mfa_challenge_token": "reset-token-abc123",
"code": "example-value"
}'{
"data": {
"user": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "user@example.com",
"role": "user",
"subscriptionTier": "free",
"username": "...",
"name": "...",
"bio": "...",
"timezone": "...",
"websiteUrl": "...",
"avatarUrl": "...",
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z",
"deletedAt": "2026-01-15T10:30:00Z",
"isActive": true,
"hasAvatar": true,
"usernameConfirmed": true
},
"sessionToken": "...",
"expiresAt": "2026-01-15T10:30:00Z",
"remainingCodes": 0
}
}