Registry↗Dashboard↗

Authentication

User authentication, sessions, and API keys

32 endpoints

Register a new user

emailrequiredstringemail
passwordrequiredstring
201User registered successfully. A welcome email is dispatched asynchronously; SMTP failures do not affect this response.
400Validation failed
409Email already exists

Response fields

dataobject
messagestring
POST/api/v1/auth/register
curl -X POST "https://api.uluops.ai/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'
Response
{
  "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

emailrequiredstringemail
passwordrequiredstring
200Login successful
400Validation failed
401Missing or invalid authentication

Response fields

dataobject
POST/api/v1/auth/login
curl -X POST "https://api.uluops.ai/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!"
  }'
Response
{
  "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.

providerrequiredstringpath
googlegithub
originrequiredstringquery

Initiating frontend origin. Exact-matched against OAUTH_ALLOWED_ORIGINS.

returnTostringquery

Post-login path. Must start with '/'; '//' and URL schemes are rejected (sanitized to '/').

intentstringquery
signinlink
Default: signin
302Redirect to the provider authorization URL. Sets the oauth_state cookie.
400Validation failed
401intent=link without a valid session
404Unknown or unconfigured (disabled) provider
GET/api/v1/auth/oauth/{provider}/authorize
curl -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).

providerrequiredstringpath
googlegithub
codestringquery

Authorization code from the provider. Absent on user denial → provider_error redirect.

statestringquery

Signed state token minted at authorize time.

302Always. See the description for the session/MFA/error redirect contract.
GET/api/v1/auth/oauth/{provider}/callback
curl -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).

Requires authentication
200Linked providers (empty array when none)
401Missing or invalid authentication

Response fields

dataLinkedProvider[]
GET/api/v1/auth/oauth/providers
curl -X GET "https://api.uluops.ai/api/v1/auth/oauth/providers" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "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).

Requires authentication
providerrequiredstringpath
googlegithub
200Provider unlinked
401Missing or invalid authentication
404Provider not linked to this user (or unknown provider name)
409Two distinct 409 conditions, discriminated by the error `code`: (1) `LAST_AUTH_METHOD` — terminal: the link is the only remaining sign-in method and cannot be removed ("Add a password or connect another provider first"). Do NOT retry; add a method first. (2) `CONCURRENT_MODIFICATION` — transient: another change to the user's sign-in methods was in progress (lock conflict). SAFE TO RETRY.
500Unexpected failure disconnecting the provider — safe to retry.

Response fields

dataobject
DELETE/api/v1/auth/oauth/{provider}
curl -X DELETE "https://api.uluops.ai/api/v1/auth/oauth/google" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "data": {
    "removed": true
  }
}

Request password reset email

emailrequiredstringemail
200Reset email sent (if email exists)

Response fields

messagestring
POST/api/v1/auth/forgot-password
curl -X POST "https://api.uluops.ai/api/v1/auth/forgot-password" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'
Response
{
  "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.

tokenrequiredstring
passwordrequiredstring
200Password reset successful
400Invalid or expired token

Response fields

messagestring
POST/api/v1/auth/reset-password
curl -X POST "https://api.uluops.ai/api/v1/auth/reset-password" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "reset-token-abc123",
    "password": "SecurePass123!"
  }'
Response
{
  "message": "..."
}

Logout current session

Requires authentication
200Current session terminated
401Missing or invalid authentication

Response fields

messagestring
POST/api/v1/auth/logout
curl -X POST "https://api.uluops.ai/api/v1/auth/logout" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "message": "..."
}

Logout from all sessions

Requires authentication
200All sessions terminated
401Missing or invalid authentication

Response fields

messagestring
POST/api/v1/auth/logout-all
curl -X POST "https://api.uluops.ai/api/v1/auth/logout-all" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "message": "..."
}

List current user's sessions

Requires authentication
200List of sessions
401Missing or invalid authentication

Response fields

dataSession[]
GET/api/v1/auth/sessions
curl -X GET "https://api.uluops.ai/api/v1/auth/sessions" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "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

Requires authentication
idrequiredstringuuidpath

Session UUID

204Session deleted
401Missing or invalid authentication
404Resource not found
DELETE/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)

Requires authentication
passwordrequiredstring
200Password set
401Missing or invalid authentication

Response fields

messagestring
POST/api/v1/auth/password
curl -X POST "https://api.uluops.ai/api/v1/auth/password" \
  -H "Authorization: Bearer $ULUOPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "SecurePass123!"
  }'
Response
{
  "message": "..."
}

Change password (requires current password)

Requires authentication
currentPasswordrequiredstring
newPasswordrequiredstring
200Password changed
400Current password incorrect
401Missing or invalid authentication

Response fields

messagestring
PUT/api/v1/auth/password
curl -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!"
  }'
Response
{
  "message": "..."
}

Get current user info

Requires authentication
200Current user
401Missing or invalid authentication

Response fields

dataobject
GET/api/v1/auth/me
curl -X GET "https://api.uluops.ai/api/v1/auth/me" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "data": "..."
}

Get current user profile

Requires authentication
200User profile
401Missing or invalid authentication

Response fields

dataobject
GET/api/v1/auth/profile
curl -X GET "https://api.uluops.ai/api/v1/auth/profile" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "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

Requires authentication
usernamestring
Pattern: ^[a-z][a-z0-9_]{2,29}$
namestring
biostring
timezonestring
Pattern: ^[A-Za-z_]+/[A-Za-z_]+$
websiteUrlstring
avatarstring

Base64-encoded image (max 500KB)

avatarMimeTypestring
image/pngimage/jpegimage/gifimage/webp
200Profile updated
400Validation failed
401Missing or invalid authentication

Response fields

dataobject
messagestring
PATCH/api/v1/auth/profile
curl -X PATCH "https://api.uluops.ai/api/v1/auth/profile" \
  -H "Authorization: Bearer $ULUOPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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.

Requires authentication
usernamerequiredstring
200Username confirmed
400Validation failed
401Missing or invalid authentication

Response fields

dataobject
PATCH/api/v1/auth/username
curl -X PATCH "https://api.uluops.ai/api/v1/auth/username" \
  -H "Authorization: Bearer $ULUOPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "developer1"
  }'
Response
{
  "data": {
    "username": "...",
    "confirmed": true,
    "personalOrgSlug": "..."
  }
}

Check username availability

usernamerequiredstringpath
200Availability result

Response fields

dataobject
GET/api/v1/auth/check-username/{username}
curl -X GET "https://api.uluops.ai/api/v1/auth/check-username/developer1"
Response
{
  "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.

Requires authentication
200Avatar image
401Missing or invalid authentication
404No avatar set
GET/api/v1/auth/avatar
curl -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.

Requires authentication
204Avatar deleted
401Missing or invalid authentication
404No avatar to delete
DELETE/api/v1/auth/avatar
curl -X DELETE "https://api.uluops.ai/api/v1/auth/avatar" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"

List API keys

Requires authentication
200List of API keys
401Missing or invalid authentication

Response fields

dataApiKey[]
countinteger

Total number of API keys

GET/api/v1/auth/keys
curl -X GET "https://api.uluops.ai/api/v1/auth/keys" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "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

Requires authentication
namestring
expiresAtstringdate-time
201API key created (key shown only once)
401Missing or invalid authentication

Response fields

dataobject
POST/api/v1/auth/keys
curl -X POST "https://api.uluops.ai/api/v1/auth/keys" \
  -H "Authorization: Bearer $ULUOPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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

Requires authentication
idrequiredstringuuidpath

API Key UUID

204API key deleted
401Missing or invalid authentication
404Resource not found
DELETE/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

Requires authentication
200TOTP secret and otpauth URI for QR code
401Missing or invalid authentication

Response fields

dataobject
POST/api/v1/auth/totp/setup
curl -X POST "https://api.uluops.ai/api/v1/auth/totp/setup" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "data": {
    "secret": "...",
    "otpauth_uri": "..."
  }
}

Verify TOTP code to enable TOTP

Requires authentication
coderequiredstring

6-digit TOTP code

Pattern: ^\d{6}$
200TOTP enabled
400Validation failed
401Missing or invalid authentication

Response fields

messagestring
POST/api/v1/auth/totp/verify
curl -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"
  }'
Response
{
  "message": "..."
}

Verify TOTP code during MFA login

mfa_challenge_tokenrequiredstring
coderequiredstring
Pattern: ^\d{6}$
rememberMeboolean
Default: false
200Login successful
400Validation failed
429Rate limited

Response fields

dataobject
POST/api/v1/auth/totp/login
curl -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"
  }'
Response
{
  "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)

Requires authentication
passwordrequiredstring
200TOTP disabled
400Validation failed
401Missing or invalid authentication

Response fields

messagestring
DELETE/api/v1/auth/totp
curl -X DELETE "https://api.uluops.ai/api/v1/auth/totp" \
  -H "Authorization: Bearer $ULUOPS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "SecurePass123!"
  }'
Response
{
  "message": "..."
}

Generate new recovery codes

Replaces any existing codes. Requires at least one MFA method enabled.

Requires authentication
200Recovery codes generated
400Validation failed
401Missing or invalid authentication

Response fields

dataobject
POST/api/v1/auth/recovery-codes/generate
curl -X POST "https://api.uluops.ai/api/v1/auth/recovery-codes/generate" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "data": {
    "codes": [],
    "count": 0
  }
}

Get remaining recovery code count

Requires authentication
200Recovery code status
401Missing or invalid authentication

Response fields

dataobject
GET/api/v1/auth/recovery-codes/status
curl -X GET "https://api.uluops.ai/api/v1/auth/recovery-codes/status" \
  -H "Authorization: Bearer $ULUOPS_TOKEN"
Response
{
  "data": {
    "remaining": 0,
    "total": 0
  }
}

Regenerate recovery codes (requires password)

Requires authentication
passwordrequiredstring
200Recovery codes regenerated
400Validation failed
401Missing or invalid authentication

Response fields

dataobject
POST/api/v1/auth/recovery-codes/regenerate
curl -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!"
  }'
Response
{
  "data": {
    "codes": [],
    "count": 0
  }
}

Verify recovery code during MFA login

mfa_challenge_tokenrequiredstring
coderequiredstring
rememberMeboolean
Default: false
200Login successful
400Validation failed
429Rate limited

Response fields

dataobject
POST/api/v1/auth/recovery-codes/verify
curl -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"
  }'
Response
{
  "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
  }
}