> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scute.io/llms.txt
> Use this file to discover all available pages before exploring further.

# User Identifier Verification

# 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:

```bash theme={null}
POST https://api.scute.io/v1/verify/:app_id/verifications
```

#### Authentication

This endpoint requires M2M (Machine-to-Machine) authentication:

```bash theme={null}
# 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

| Parameter                  | Type   | Required | Description                                            |
| -------------------------- | ------ | -------- | ------------------------------------------------------ |
| `identifier`               | string | Yes      | The new email address or phone number to verify        |
| `channel`                  | string | Yes      | Must be "user\_identifier" for identifier changes      |
| `verification_type`        | string | Yes      | Must be "user\_identifier" for identifier verification |
| `reason`                   | string | No       | A description of why the identifier is being changed   |
| `metadata`                 | object | Yes      | Contains user ID and identifier type information       |
| `metadata.user_id`         | string | Yes      | The ID of the user whose identifier will be changed    |
| `metadata.identifier_type` | string | Yes      | Must be either "email" or "phone"                      |

#### Example Request

```javascript theme={null}
// 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
```

```javascript theme={null}
// 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

```bash theme={null}
# 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

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:

```bash theme={null}
POST https://api.scute.io/v1/verify/:app_id/verifications/verify
```

```javascript theme={null}
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

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

```json theme={null}
{
  "error": "This email is already used by another user in this workspace",
  "error_code": "identifier_already_exists"
}
```

### Invalid Format

```json theme={null}
{
  "error": "Invalid email format",
  "error_code": "invalid_email_format"
}
```

### Invalid Type

```json theme={null}
{
  "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