Password Authentication
Email and password-based authentication endpoints including registration, login, verification, and password reset.
Endpoints
| Method | Path | Description |
|---|---|---|
POST |
/api/auth/register |
Register new user |
GET |
/auth/verify-email |
Verify email address |
POST |
/api/auth/login |
Login with email/password |
POST |
/api/auth/forgot-password |
Request password reset |
POST |
/api/auth/reset-password |
Reset password with token |
POST |
/api/auth/resend-verification |
Resend verification email |
POST /api/auth/register
Register a new user account with email and password.
Synopsis
| Property | Value |
|---|---|
| Authentication | Public |
| Rate Limit | 10/minute |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
Yes | Valid email address |
password |
string |
Yes | Password (minimum 8 characters) |
org_slug |
string |
No | Organization slug for branded emails |
Example Request
curl -X POST https://sso.example.com/api/auth/register \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "securepassword123",
"org_slug": "acme-corp"
}'
Response (200 OK)
{
"message": "Registration successful. Please check your email to verify your account."
}
Errors
| Status | Condition |
|---|---|
400 |
Invalid email format |
400 |
Password too weak (< 8 characters) |
409 |
User with email already exists |
GET /auth/verify-email
Verify user’s email address using token from verification email.
Synopsis
| Property | Value |
|---|---|
| Authentication | Public |
| Token Lifetime | 24 hours |
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
token |
string |
Yes | Email verification token (UUID) |
Example Request
curl -X GET "https://sso.example.com/auth/verify-email?token=550e8400-e29b-41d4-a716-446655440000"
Response (200 OK): HTML page confirming email verification
Errors
| Status | Condition |
|---|---|
400 |
Invalid, expired, or already used token |
POST /api/auth/login
Authenticate user with email and password.
Synopsis
| Property | Value |
|---|---|
| Authentication | Public |
| Rate Limit | 10/minute |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
Yes | User’s email address |
password |
string |
Yes | User’s password |
saml_state |
string |
No | SAML state ID for SAML flows |
Example Request
curl -X POST https://sso.example.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"password": "securepassword123"
}'
Response - Without MFA (200 OK)
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"refresh_token": "550e8400-e29b-41d4-a716-446655440000",
"expires_in": 86400
}
Response - With MFA Enabled (200 OK)
{
"access_token": "preauth_token_eyJhbGciOiJSUzI1NiIs...",
"refresh_token": "",
"expires_in": 600,
"mfa_required": true
}
When mfa_required: true, the access_token is a pre-auth token that must be exchanged via MFA verification.
Errors
| Status | Condition |
|---|---|
401 |
Invalid email or password |
401 |
Email not verified |
POST /api/auth/forgot-password
Request password reset email.
Synopsis
| Property | Value |
|---|---|
| Authentication | Public |
| Rate Limit | 5/minute |
| Token Lifetime | 1 hour |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
Yes | User’s email address |
org_slug |
string |
No | Organization slug for branded emails |
Example Request
curl -X POST https://sso.example.com/api/auth/forgot-password \
-H "Content-Type: application/json" \
-d '{
"email": "user@example.com",
"org_slug": "acme-corp"
}'
Response (200 OK)
{
"message": "If an account with that email exists, a password reset link has been sent."
}
[!NOTE] Always returns success to prevent email enumeration attacks.
POST /api/auth/reset-password
Reset user’s password using token from reset email.
Synopsis
| Property | Value |
|---|---|
| Authentication | Public |
| Side Effects | Revokes all existing sessions |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
token |
string |
Yes | Password reset token (UUID) |
new_password |
string |
Yes | New password (minimum 8 characters) |
Example Request
curl -X POST https://sso.example.com/api/auth/reset-password \
-H "Content-Type: application/json" \
-d '{
"token": "550e8400-e29b-41d4-a716-446655440000",
"new_password": "newsecurepassword456"
}'
Response (200 OK)
{
"message": "Password has been reset successfully. Please log in with your new password."
}
Security Notes
- All existing sessions are revoked on password reset
- Token is single-use and deleted after use
- Token expires after 1 hour
Errors
| Status | Condition |
|---|---|
400 |
Invalid, expired, or already used token |
400 |
Password too weak |
POST /api/auth/resend-verification
Resend email verification link.
Synopsis
| Property | Value |
|---|---|
| Authentication | Public |
| Rate Limit | 3/minute |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
email |
string |
Yes | User’s email address |
Response (200 OK)
{
"message": "If an account with that email exists and is not verified, a verification link has been sent."
}
[!NOTE] Always returns success to prevent email enumeration attacks.
Password Requirements
| Requirement | Value |
|---|---|
| Minimum length | 8 characters |
| Maximum length | 128 characters |
Passwords are hashed using Argon2id before storage.