Skip to content

Users API

Manage user accounts, profiles, and authentication settings.

Endpoints

Get Current User

GET /api/v1/user

Get the currently authenticated user's profile.

Response

{
  "userId": "user123xyz",
  "email": "[email protected]",
  "displayName": "John Doe",
  "avatarUrl": "https://cdn.usetotis.com/avatars/user123.png",
  "preferredLanguage": "en",
  "timezone": "America/New_York",
  "status": "ACTIVE",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-02-01T14:20:00Z"
}

User Status Values

Status Description
VERIFYING Email verification pending
ACTIVE Account fully activated

Get User Workspaces

GET /api/v1/user/workspaces

List all workspaces the user belongs to.

Response

[
  {
    "workspaceId": "ws123",
    "name": "My Company",
    "slug": "my-company",
    "pictureUrl": "https://cdn.usetotis.com/images/ws123.png",
    "maxUsers": 10,
    "maxProjects": 5,
    "maxStorage": 10737418240,
    "storageUsed": 2147483648,
    "permissions": [
      "WORKSPACE_READ",
      "WORKSPACE_EDIT",
      "PROJECT_CREATE",
      "BUILD_CREATE"
    ]
  },
  {
    "workspaceId": "ws456",
    "name": "Client Project",
    "slug": "client-project",
    "pictureUrl": null,
    "permissions": [
      "WORKSPACE_READ",
      "PROJECT_READ",
      "BUILD_DOWNLOAD"
    ]
  }
]

Get Workspace Projects

GET /api/v1/user/workspaces/{workspaceSlug}/projects

List all projects in a workspace that the user has access to.

Path Parameters

Parameter Type Description
workspaceSlug string Workspace identifier

Response

[
  {
    "workspace": {
      "workspaceId": "ws123",
      "name": "My Company",
      "slug": "my-company"
    },
    "project": {
      "projectId": "proj123",
      "name": "iOS App",
      "projectSlug": "ios-app",
      "repository": "https://github.com/company/ios-app",
      "imageUrl": "https://cdn.usetotis.com/images/proj123.png"
    },
    "permissions": [
      "PROJECT_READ",
      "PROJECT_EDIT",
      "BUILD_CREATE"
    ]
  }
]

Update User Profile

PUT /api/v1/user/profile

Update the current user's profile information.

Request Body

{
  "displayName": "John Smith",
  "avatarUrl": "https://example.com/avatar.png",
  "preferredLanguage": "en",
  "timezone": "America/Los_Angeles"
}
Field Type Required Description
displayName string No User's display name
avatarUrl string No URL to avatar image
preferredLanguage string No ISO language code
timezone string No IANA timezone identifier

Response

Returns the updated user object.

Change Password

POST /api/v1/user/security/change-password

Change the current user's password.

Request Body

{
  "newPassword": "newSecurePassword123!"
}
Field Type Required Description
newPassword string Yes New password

Response

HTTP 200 OK on success.

Password Requirements

Passwords should be at least 8 characters and include a mix of letters, numbers, and special characters.

Initiate Password Reset

POST /api/v1/user/security/reset-password

Request a password reset email. No authentication required.

Request Body

{
  "email": "[email protected]"
}

Response

Always returns HTTP 200 OK, regardless of whether the email exists (for security).

Security Consideration

For security reasons, this endpoint always returns success even if the email doesn't exist in the system.

Confirm Password Reset

POST /api/v1/user/security/reset-password/confirm

Complete the password reset process with the token from the email.

Request Body

{
  "token": "reset-token-from-email",
  "newPassword": "newSecurePassword123!"
}

Onboarding Endpoints

Sign Up

POST /api/v1/onboarding/signup

Register a new user account.

Request Body

{
  "email": "[email protected]",
  "password": "securePassword123!",
  "displayName": "New User",
  "captchaToken": "turnstile-captcha-token"
}
Field Type Required Description
email string Yes User's email address
password string Yes Password (min 8 chars)
displayName string No Display name
captchaToken string Yes Cloudflare Turnstile token

Response

{
  "userId": "user123xyz",
  "email": "[email protected]",
  "status": "VERIFYING"
}

Resend Verification Email

POST /api/v1/onboarding/signup/resend-verification

Resend the email verification link.

Request Body

{
  "email": "[email protected]",
  "captchaToken": "turnstile-captcha-token"
}

Save Onboarding Profile

POST /api/v1/onboarding/profile

Complete the onboarding profile after email verification.

Request Body

{
  "companyName": "My Company",
  "role": "Developer",
  "useCase": "Mobile app distribution"
}

Email Verification

GET /api/v1/verification/verify

Verify an email address using the token from the verification email.

Query Parameters

Parameter Type Description
token string Verification token from email

Response

HTTP 302 redirect to the frontend with verification status:

  • Success: ?verificationComplete=true
  • Invalid token: ?verificationComplete=false&error=invalid_token
  • Expired token: ?verificationComplete=false&error=expired_token

This endpoint handles three verification types:

  1. Email Verification - New account activation
  2. Password Reset - Password change confirmation
  3. Workspace Invitation - Accept workspace invite