Documentation Menu

Authentication endpoints

Register a new user

POST /auth/register

Create a new user account with an email, password, and display name. Returns a session token that can be used for subsequent authenticated requests. If email verification is enabled on the server, a verification email will be sent.

Request body 

{
  "email": "alice@example.com",
  "password": "securepassword123",
  "display_name": "Alice Chen"
}

Responses

200 User registered successfully

{
  "user": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "email": "alice@example.com",
    "email_verified_at": "2025-01-15T09:30:00Z",
    "display_name": "Alice Chen",
    "avatar_url": "/files/01JQ3KMT6B/download?sig=abc",
    "gravatar_url": "https://www.gravatar.com/avatar/abc123?d=mp",
    "status": "In a meeting",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  },
  "token": "enz_v1_01JQ3KMWX8FVN4CPRD6BHTYGSZ"
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

Log in a user

POST /auth/login

Authenticate with email and password. Returns a session token and user object. The token should be included as a Bearer token in the Authorization header for all authenticated requests.

Request body 

{
  "email": "alice@example.com",
  "password": "securepassword123"
}

Responses

200 User logged in successfully

{
  "user": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "email": "alice@example.com",
    "email_verified_at": "2025-01-15T09:30:00Z",
    "display_name": "Alice Chen",
    "avatar_url": "/files/01JQ3KMT6B/download?sig=abc",
    "gravatar_url": "https://www.gravatar.com/avatar/abc123?d=mp",
    "status": "In a meeting",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  },
  "token": "enz_v1_01JQ3KMWX8FVN4CPRD6BHTYGSZ"
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

Log out the current user

POST /auth/logout

Invalidate the current session token. After logging out, the token can no longer be used for authenticated requests.

Responses

200 User logged out successfully

{
  "success": true
}

Request a password reset

POST /auth/forgot-password

Send a password reset email to the specified address. Always returns success regardless of whether the email exists, to prevent email enumeration. Requires email to be enabled on the server.

Request body 

{
  "email": "alice@example.com"
}

Responses

200 Password reset email sent

{
  "success": true,
  "message": "string"
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

Reset password with token

POST /auth/reset-password

Set a new password using a reset token received via email. The token is single-use and expires after a configured duration.

Request body 

{
  "token": "enz_v1_01JQ3KMWX8FVN4CPRD6BHTYGSZ",
  "new_password": "newsecurepassword456"
}

Responses

200 Password reset successfully

{
  "success": true
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

Verify email address with token

POST /auth/verify-email

Confirm ownership of an email address using a verification token received via email. The token is single-use.

Request body 

{
  "token": "enz_v1_01JQ3KMWX8FVN4CPRD6BHTYGSZ"
}

Responses

200 Email verified successfully

{
  "success": true
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

Resend verification email

POST /auth/resend-verification

Requires authentication.

Request a new email verification link. Useful if the original verification email was lost or expired. Requires the user to be logged in but not yet verified.

Responses

200 Verification email sent

{
  "success": true
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

Get current user info

GET /auth/me

Returns the currently authenticated user along with their workspace memberships. This is typically the first call a client makes after login to bootstrap the UI.

Responses

200 Current user information

{
  "user": {
    "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
    "email": "alice@example.com",
    "email_verified_at": "2025-01-15T09:30:00Z",
    "display_name": "Alice Chen",
    "avatar_url": "/files/01JQ3KMT6B/download?sig=abc",
    "gravatar_url": "https://www.gravatar.com/avatar/abc123?d=mp",
    "status": "In a meeting",
    "created_at": "2025-01-15T09:30:00Z",
    "updated_at": "2025-01-15T09:30:00Z"
  },
  "workspaces": [
    {
      "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V",
      "name": "general",
      "icon_url": "/files/01JQ3KMT6B/download?sig=abc",
      "role": "owner",
      "sort_order": 1,
      "ban": {
        "reason": "Repeated spam",
        "expires_at": "2025-01-15T09:30:00Z"
      }
    }
  ]
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

Register a device token for push notifications

POST /auth/device-tokens

Requires authentication.

Register a device token for push notifications (FCM for Android, APNs for iOS). Each token is associated with the current user and session. Re-registering an existing token updates its association.

Request body 

{
  "token": "enz_v1_01JQ3KMWX8FVN4CPRD6BHTYGSZ",
  "platform": "fcm",
  "device_id": "string"
}

Responses

200 Device token registered

{
  "id": "01JQ3KMN7XFGY4P6WBR2SZTA9V"
}

400 Bad request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters"
  }
}

401 Unauthorized

{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

Unregister a device token

DELETE /auth/device-tokens/{id}

Requires authentication.

Remove a previously registered device token to stop receiving push notifications on that device.

Parameters

Name In Type Description
id path string The device token record ID

Responses

  • 204 Device token removed 401 Unauthorized
{
  "error": {
    "code": "NOT_AUTHENTICATED",
    "message": "Not authenticated"
  }
}

404 Not found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}