# Move your existing users to Mocco

If your service already has users and its own sign-in, you can move them to Mocco without asking anyone to sign in
again. The move has three steps:

1. **Import** your users into an [identity environment](https://www.mocco.club/docs/en/articles/mhzsnt-environments), each with your own user ID as `externalId`
   and the provider accounts they signed in with.
2. **Run both** for a while. New sign-ins go through Mocco; people who are already signed in keep their old session.
3. **Exchange** each old session for a Mocco session on your server, the next time that person's app talks to it. When
   nobody uses old sessions any more, turn the old sign-in off.

## 1. Import your users

Give each user an `externalId` (your user ID), an `email` if you have one, and the provider accounts they used
(`provider` and the provider's user ID as `subject`). Import them in batches of up to 1,000 users, either by asking your
agent to use the `mocco_identity_users_import` tool, or from your server with a **secret** key that has the
`identity:users` scope and is bound to the environment:

```sh
curl -s https://www.mocco.club/api/ext/v1/identity/users/import \
  -H "Authorization: Bearer $MOCCO_USERS_KEY" \
  -H 'content-type: application/json' \
  -d '{"users":[{"externalId":"your-user-id","email":"minji@example.com","accounts":[{"provider":"google","subject":"1098…"}]}]}'
```

Anything that already exists in the environment (the email, the `externalId` or a provider account) skips that user;
nothing is overwritten. The answer pairs each `externalId` with its new Mocco user ID.

To check one user later, look them up by exactly one of your user ID, their email or a provider account:

```sh
curl -s "https://www.mocco.club/api/ext/v1/identity/users?externalId=your-user-id" \
  -H "Authorization: Bearer $MOCCO_USERS_KEY"
```

The answer is `{ "user": … }` with the user's sign-in methods, each provider with its `subject`, or `{ "user": null }`.
Your agent can do the same with `mocco_identity_users_lookup`. In the app, `me()` shows the same `subject` for each linked
provider.

## 2. Create an exchange key

On the project's **API keys** page, create a **secret** key with the `identity:exchange` scope and pick the environment
you imported into. Give it an expiry around the end of your move. Keep it on your server only: it can start a session
for any user of that environment.

A sign-in key (`identity:auth`) can't exchange, and an exchange key can't sign people in. Use one of each.

## 3. Exchange a live session

When your server sees a request with a valid session of your old sign-in, and that person has no Mocco session yet, ask
Mocco for one:

```sh
curl -s https://www.mocco.club/api/ext/v1/identity/sessions/exchange \
  -H "Authorization: Bearer $MOCCO_EXCHANGE_KEY" \
  -H 'content-type: application/json' \
  -d '{"externalId":"your-user-id"}'
```

The answer is the same session a sign-in gets:

```json
{ "accessToken": "…", "refreshToken": "…", "expiresIn": 900, "user": { "id": "…", "externalId": "your-user-id", … } }
```

Hand the tokens to your app the way you hand out your own (an HttpOnly cookie, or the app's secure storage), then end
the old session. From then on the app refreshes the Mocco session as usual.

Only users already in the environment can be exchanged: an unknown `externalId` gets `404` and nothing is created. A
blocked user gets `401`. Each user can be exchanged five times a minute and each key 60 times a minute; beyond that you
get `429` with `Retry-After`. Every exchange appears in the audit log as "Exchanged a service session for an app user's
Mocco session", with the key that asked.

## When you're done

Revoke the exchange key on the **API keys** page. Sessions it started keep working like any other session; you can revoke
a user's sessions or block them from the **App users** page.

## Troubleshooting

| Answer | Cause | Fix |
|---|---|---|
| `401 secret_key_from_browser` | The request came from a web page | Call from your server only |
| `403 wrong_key_kind` | A publishable key | Use a secret key |
| `403 insufficient_scope` | The key lacks `identity:exchange` | Create a key with that scope |
| `404 not_found` | No user with that `externalId` in the key's environment | Import the user first, or check the key's environment |
| `401 invalid_session` | The user is blocked | Unblock them on the **App users** page if that was a mistake |
