User Identifier Verification

User identifier verification allows you to securely change a user's email address or phone number after verifying ownership of the new identifier. This is essential for maintaining account security when users need to update their contact information.

Overview

The user identifier verification process involves:

1. Creating a verification request for the new email or phone number
2. Sending an OTP code to the new identifier
3. User verifies ownership by entering the OTP code
4. Automatic update of the user's identifier upon successful verification

Supported Identifier Types

• Email addresses: Users can change their registered email address
• Phone numbers: Users can change their registered phone number

Security Features

Duplicate Prevention

The system prevents duplicate identifiers within the same workspace:

• No two users in the same workspace can have the same email address
• No two users in the same workspace can have the same phone number
• Users in different workspaces can have the same identifier

Verification Required

• Users must verify ownership of the new identifier before the change takes effect
• OTP codes are sent directly to the new identifier
• The old identifier remains active until verification is complete

Creating User Identifier Verifications

API Method

Send a POST request to create a user identifier verification:

POST https://api.scute.io/v1/verify/:app_id/verifications

Request Parameters

Parameter	Type	Required	Description
to_user_id	string	Yes	The ID of the user whose identifier will be changed
new_identifier	string	Yes	The new email address or phone number
identifier_type	string	Yes	Must be either "email" or "phone"
reason	string	No	A description of why the identifier is being changed

Example Request

// Change user's email address
const response = await fetch('https://api.scute.io/v1/verify/your-app-id/verifications', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_SCUTE_API_KEY'
  },
  body: JSON.stringify({
    to_user_id: 'user-uuid-here',
    new_identifier: 'newemail@example.com',
    identifier_type: 'email',
    reason: 'User requested email change'
  })
});

const data = await response.json();
console.log(data.verification_id); // Use this to track verification status

// Change user's phone number
const response = await fetch('https://api.scute.io/v1/verify/your-app-id/verifications', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_SCUTE_API_KEY'
  },
  body: JSON.stringify({
    to_user_id: 'user-uuid-here',
    new_identifier: '+1234567890',
    identifier_type: 'phone',
    reason: 'User requested phone change'
  })
});

Response

The API returns a verification request object with:

• verification_id: Unique identifier for tracking the verification
• status: Initially set to "pending"
• channel: Set to "user_identifier"
• metadata: Contains the new identifier and type information

Verification Process

1. OTP Delivery

After creating the verification request:

• An OTP code is sent to the new identifier
• For email: OTP is sent via email
• For phone: OTP is sent via SMS (when SMS is configured)

2. Code Verification

Users verify the OTP code using:

POST https://api.scute.io/v1/verify/:app_id/verifications/verify

const response = await fetch('https://api.scute.io/v1/verify/your-app-id/verifications/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_SCUTE_API_KEY'
  },
  body: JSON.stringify({
    verification_id: 'verification-uuid-here',
    code: '123456'
  })
});

3. Automatic Update

Upon successful verification:

• The user's identifier is automatically updated in the database
• The confirmation timestamp is set (email_confirmed_at or phone_confirmed_at)
• The verification status changes to "verified"

Error Handling

The API returns specific error codes for common scenarios:

Duplicate Identifier

{
  "error": "This email is already used by another user in this workspace",
  "error_code": "identifier_already_exists"
}

Invalid Format

{
  "error": "Invalid email format",
  "error_code": "invalid_email_format"
}

Invalid Type

{
  "error": "Identifier type must be email or phone", 
  "error_code": "invalid_identifier_type"
}

Best Practices

1. User Experience

• Always inform users that they'll receive a verification code at their new identifier
• Provide clear instructions about checking spam folders for email verifications
• Set appropriate expectations for delivery time

2. Security

• Validate identifier formats on the client side before sending requests
• Handle duplicate identifier errors gracefully
• Consider rate limiting verification requests to prevent abuse

3. Error Handling

• Display specific error messages to help users understand what went wrong
• Provide retry mechanisms for failed verifications
• Log verification attempts for audit purposes

Integration with Dashboard

The Scute dashboard provides a user-friendly interface for identifier changes:

• Users can initiate identifier changes through the profile settings
• Real-time validation prevents duplicate identifiers
• Automatic redirect to verification status page after request creation

Monitoring and Analytics

Track verification metrics through:

• Verification request creation events
• Success/failure rates by identifier type
• Time-to-completion analytics
• User adoption of identifier change features

Webhooks

Configure webhooks to receive notifications when:

• Identifier verification requests are created
• Verifications are completed successfully
• Verifications fail or expire

Webhook functionality is currently in development.