Verify Email

Set password and verify email for invited users. This endpoint is used by new users who have been invited to an organization.

Request

POST /api/v1/auth/set-password

Authentication

Public - No authentication required (invite token is provided in request body).

Request Body

{
  "inviteToken": "invite_abc123xyz789...",
  "password": "SecurePass123!"
}

Name	Type	Required	Description
inviteToken	string	Yes	Invitation token received via email when the user was created
password	string	Yes	Password to set for the account (8-128 characters, must comply with organization password policy)

Response

Success Response (200 OK)

Upon successful password setup and email verification, the user is automatically authenticated:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "expiresIn": 3600,
  "tokenType": "Bearer",
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "[email protected]",
    "name": "Jane Smith",
    "isOrgAdmin": false,
    "organizationId": "223e4567-e89b-12d3-a456-426614174001",
    "organizationName": "Acme Corporation",
    "organizationSlug": "acme-corporation",
    "subscriptionTier": "BUSINESS",
    "mfaEnabled": false
  }
}

Response Fields

Field	Type	Description
accessToken	string	JWT access token for authenticated requests
refreshToken	string	Refresh token to obtain new access tokens
expiresIn	number	Access token expiration time in seconds
tokenType	string	Token type (always "Bearer")
user	object	User information object
user.id	string	Unique user ID (UUID)
user.email	string	User's email address
user.name	string	User's full name
user.isOrgAdmin	boolean	Whether the user is an organization admin
user.organizationId	string	Organization ID (UUID)
user.organizationName	string	Organization name
user.organizationSlug	string	URL-friendly organization identifier
user.subscriptionTier	string	Subscription tier (FREE, BUSINESS, ENTERPRISE, PLATFORM)
user.mfaEnabled	boolean	Whether MFA is enabled for this user (initially false)

Password Policy Validation

The password must comply with the organization's password policy. Common requirements include:

• Minimum length: 8 characters
• Maximum length: 128 characters
• May require uppercase letters
• May require lowercase letters
• May require numbers
• May require special characters

Error Responses

Status Code	Description
400 Bad Request	Invalid request body (missing required fields)
401 Unauthorized	Invalid, expired, or already-used invite token
403 Forbidden	User or organization is suspended
422 Unprocessable Entity	Password fails organization password policy validation
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error occurred

Password Policy Error Response

{
  "error": "Password does not meet policy requirements",
  "details": {
    "minLength": 8,
    "maxLength": 128,
    "requireUppercase": true,
    "requireLowercase": true,
    "requireNumbers": true,
    "requireSpecialChars": true,
    "violations": [
      "Password must contain at least one uppercase letter",
      "Password must contain at least one number"
    ]
  }
}

Example

curl -X POST https://api.entryguard.io/api/v1/auth/set-password \
  -H "Content-Type: application/json" \
  -d '{
    "inviteToken": "invite_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a",
    "password": "SecurePass123!"
  }'

Example Response (Success)

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjNlNDU2Ny1lODliLTEyZDMtYTQ1Ni00MjY2MTQxNzQwMDAiLCJvcmdJZCI6IjIyM2U0NTY3LWU4OWItMTJkMy1hNDU2LTQyNjYxNDE3NDAwMSIsInJvbGVzIjpbIlVTRVIiXSwiaWF0IjoxNzA5MDQ5NjAwLCJleHAiOjE3MDkwNTMyMDB9.xyz123",
  "refreshToken": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "expiresIn": 3600,
  "tokenType": "Bearer",
  "user": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "email": "[email protected]",
    "name": "Jane Smith",
    "isOrgAdmin": false,
    "organizationId": "223e4567-e89b-12d3-a456-426614174001",
    "organizationName": "Acme Corporation",
    "organizationSlug": "acme-corporation",
    "subscriptionTier": "BUSINESS",
    "mfaEnabled": false
  }
}

Example Error Response (Invalid Token)

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "Invalid or expired invitation token"
}

Example Error Response (Policy Violation)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "Password does not meet policy requirements",
  "details": {
    "minLength": 8,
    "requireUppercase": true,
    "requireLowercase": true,
    "requireNumbers": true,
    "requireSpecialChars": true,
    "violations": [
      "Password must contain at least one special character"
    ]
  }
}

Usage Notes

Invitation Flow

When an organization admin creates a new user via POST /api/v1/users:

1. The new user is created with a pending status
2. An invitation email is sent to the user's email address
3. The email contains a link with the invite token, typically in format: https://app.entryguard.io/set-password?token={inviteToken}
4. The user clicks the link and is directed to a password setup form
5. The user submits their password via this endpoint
6. The user's email is verified and they are authenticated

Token Lifecycle

• Invite tokens are single-use and invalidated immediately after successful password setup
• Tokens typically expire after 7 days
• Attempting to reuse a token will result in a 401 Unauthorized error
• If a token expires, an admin must resend the invitation (delete and recreate the user)

Email Verification

By successfully setting a password with the invite token, the user's email address is automatically verified. There is no separate email verification step.

MFA Enrollment

If the organization requires MFA (organizationMfaRequired: true), the user will need to enroll in MFA on their first login after setting their password. This is handled by the login flow.

Frontend Implementation Example

// JavaScript example - parse token from URL and set password
async function setPassword() {
  // Extract token from URL query parameter
  const urlParams = new URLSearchParams(window.location.search);
  const inviteToken = urlParams.get('token');
  const password = document.getElementById('password').value;
  const confirmPassword = document.getElementById('confirmPassword').value;

  if (!inviteToken) {
    alert('Invalid invitation link');
    return;
  }

  if (password !== confirmPassword) {
    alert('Passwords do not match');
    return;
  }

  try {
    const response = await fetch('https://api.entryguard.io/api/v1/auth/set-password', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        inviteToken,
        password
      })
    });

    if (response.ok) {
      const data = await response.json();

      // Store tokens
      localStorage.setItem('accessToken', data.accessToken);
      localStorage.setItem('refreshToken', data.refreshToken);
      localStorage.setItem('user', JSON.stringify(data.user));

      // Redirect to dashboard or onboarding
      window.location.href = '/dashboard';
    } else if (response.status === 401) {
      alert('Invitation link is invalid or expired. Please contact your administrator.');
    } else if (response.status === 422) {
      const error = await response.json();
      alert(`Password does not meet requirements: ${error.details.violations.join(', ')}`);
    } else {
      alert('An error occurred. Please try again.');
    }
  } catch (error) {
    console.error('Set password error:', error);
    alert('An error occurred. Please try again.');
  }
}

Related Endpoints

• Create User - Admin endpoint to invite new users (sends invitation email)
• Login - Authenticate after password is set