​

User Identifier Verification

​

Overview

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

• 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

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

​

Authentication

# Get M2M token first
curl -X POST "https://api.scute.io/v1/auth/m2m/token" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your_api_key"}'

​

Request Parameters

​

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',
    'X-Authorization': 'your_m2m_access_token'
  },
  body: JSON.stringify({
    identifier: 'newemail@example.com',
    channel: 'user_identifier',
    verification_type: 'user_identifier',
    reason: 'User requested email change',
    metadata: {
      user_id: 'user-uuid-here',
      identifier_type: 'email'
    }
  })
});

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',
    'X-Authorization': 'your_m2m_access_token'
  },
  body: JSON.stringify({
    identifier: '+1234567890',
    channel: 'user_identifier',
    verification_type: 'user_identifier',
    reason: 'User requested phone change',
    metadata: {
      user_id: 'user-uuid-here',
      identifier_type: 'phone'
    }
  })
});

​

cURL Example

# Change user's email address
curl -X POST "https://api.scute.io/v1/verify/your-app-id/verifications" \
  -H "Content-Type: application/json" \
  -H "X-Authorization: your_m2m_access_token" \
  -d '{
    "identifier": "newemail@example.com",
    "channel": "user_identifier",
    "verification_type": "user_identifier",
    "reason": "User requested email change",
    "metadata": {
      "user_id": "user-uuid-here",
      "identifier_type": "email"
    }
  }'

​

Response

• 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

• 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

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',
    'X-Authorization': 'your_m2m_access_token'
  },
  body: JSON.stringify({
    verification_id: 'verification-uuid-here',
    code: '123456'
  })
});

const result = await response.json();
if (result.verified) {
  console.log('Identifier successfully changed!');
}

​

3. Automatic Update

• 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

​

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

• 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

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

​

Webhooks

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