docs
CTRL K
GitHubDiscord
DevelopersAPI ReferenceLearnIntegrationsWebsiteGitHubDiscord
Skip to Content

Authentication

Login, token refresh, logout, OAuth and email verification. Login is form-encoded and returns a JWT for user-context flows.

Refresh access token

GET/api/v1/auth/refresh
User session

Validate the refresh token (read from the `refresh_token` httpOnly cookie) and issue a new access token. Subject to IP-based rate limiting.

Error responses
  • 401 Refresh token is missing or invalid
  • 429 Too many refresh attempts from this IP
Request

Log in with email and password

POST/api/v1/auth/login
No authentication

Authenticate a user with username (email) and password. On success, sets httpOnly access and refresh cookies and returns the user profile and tokens. Subject to IP-based rate limiting and account lockout after repeated failures. In SaaS mode, the account's email must be verified.

Request bodyapplication/x-www-form-urlencodedrequired

usernamestringrequired
passwordstringrequired
Error responses
  • 401 Incorrect email or password
  • 403 Email not verified (SaaS mode)
  • 422 Validation Error — HTTPValidationError
  • 423 Account is locked due to too many failed attempts
  • 429 Too many login attempts from this IP
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Log in via third-party provider

POST/api/v1/auth/oauth
User session

Sign in or sign up using a third-party OAuth provider (currently Google). On success, sets httpOnly access and refresh cookies and returns the user profile and tokens.

Query parameters

org_idinteger | null

Request bodyapplication/jsonrequired

emailstringrequired
providerstringrequired
access_tokenstringrequired
Error responses
  • 401 Third-party authentication failed
  • 422 Validation Error — HTTPValidationError
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Log out the current user

DELETE/api/v1/auth/logout
User session

Log out the current user by clearing the access and refresh cookies. Because JWTs are stored in httpOnly cookies, the frontend cannot clear them directly — the backend must respond with cookie-clearing headers.

Error responses
  • 401 No authenticated session was found
Request

Verify user email

POST/api/v1/auth/verify-email
User session

Verify a user's email address using the token delivered via verification email. Rate limited to 5 attempts per 5 minutes per user_uuid.

Request bodyapplication/jsonrequired

tokenstringrequired
user_uuidstringrequired
org_uuidstringrequired
emailstring | null
Error responses
  • 422 Validation Error — HTTPValidationError
  • 429 Too many verification attempts for this user
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Resend verification email

POST/api/v1/auth/resend-verification
User session

Resend the email-verification email for a user. The underlying service enforces its own rate limiting and will return a generic response whether or not an account exists.

Request bodyapplication/jsonrequired

emailstringrequired
org_idinteger | null
Error responses
  • 422 Validation Error — HTTPValidationError
  • 429 Too many verification email requests — rate limited
Request
Response
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}