Create a user and start SSO

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.

Synchronize the branch and complete the migration of existing users with ExuraCopy Support before sending branch_id in production.

Request

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": "[email protected]",
    "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.

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

{
  "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.

Previous: Synchronize branches

Next: Direct password

Enable additional access with email and password.

Getting Started

Integration Flows

Reliability

Request

Fields

Response

​Request

​Fields

​Response

Previous: Synchronize branches

Next: Direct password

Request

Fields

Response