> ## Documentation Index
> Fetch the complete documentation index at: https://crm-social.exuratech.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a user and start SSO

> Create or link a user and obtain a one-time access URL.

`POST /api/v1/sso/start` finds the user by `external_reference`, creates or links the social identity, assigns the branch, and returns a temporary SSO URL.

> [!NOTE]
>
> Synchronize the branch and complete the migration of existing users with ExuraCopy Support before sending `branch_id` in production.

## Request

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://social-api.example.com/api/v1/sso/start" \
  -H "Authorization: Bearer YOUR_CRM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference": "crm-user-127",
    "email": "customer@example.com",
    "external_provider": "CRM",
    "branch_id": 27,
    "first_name": "John",
    "last_name": "Smith",
    "create_wallets": true,
    "redirect_path": "/dashboard",
    "frontend_base_url": "https://social.example.com",
    "ttl_seconds": 60
  }'
```

## Fields

| Field | Required | Description |
| - | - | - |
| `external_reference` | Yes | Stable, unique CRM user ID. |
| `email` | Yes | User email address. |
| `external_provider` | Recommended | Source system identifier, such as `CRM`. |
| `branch_id` | Yes | CRM branch ID. It must first be registered through `/api/v1/branches/sync`. |
| `first_name` | No | First name displayed in Social Trading. |
| `last_name` | No | Last name displayed in Social Trading. |
| `create_wallets` | Yes | Use `true` to create automatic wallet accounts. |
| `redirect_path` | No | Internal path after login. |
| `frontend_base_url` | Yes | Public ExuraCopy Social Trading client URL. |
| `ttl_seconds` | No | Token lifetime from 15 to 600 seconds; 60 is recommended. |

> [!WARNING]
>
> Send the external ID used by your CRM, not the internal ID returned by ExuraCopy when synchronizing the branch. An unregistered branch produces a `422` response.

For an existing user, an explicit `branch_id` may update the assignment. If the user moves to another branch, first confirm with ExuraCopy how this affects products and active subscriptions.

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "redirect_url": "https://social.example.com/api/auth/sso?token=ONE_TIME_TOKEN",
  "expires_at": "2026-07-22T18:00:00Z",
  "user_id": 42,
  "external_reference": "crm-user-127",
  "user_status": "CREATED",
  "created_user": true,
  "wallet_accounts_created": 1
}
```

The CRM must immediately redirect the browser to `redirect_url`. Do not consume the token from the backend or attempt to reuse it.

| `user_status` | Meaning |
| - | - |
| `CREATED` | The user was created in ExuraCopy Social Trading. |
| `EXISTING` | A user associated with the `external_reference` already existed. |
| `LINKED_EXISTING_EMAIL` | An existing identity without an external reference was linked. |

> [card] [Previous: Synchronize branches](https://crm-social.exuratech.com/guides/branches.md)
>
> Register the branch before starting SSO.

> [card] [Next: Direct password](https://crm-social.exuratech.com/guides/password.md)
>
> Enable additional access with email and password.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.