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

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:

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:

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:

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

AnswerCauseFix
401 secret_key_from_browserThe request came from a web pageCall from your server only
403 wrong_key_kindA publishable keyUse a secret key
403 insufficient_scopeThe key lacks identity:exchangeCreate a key with that scope
404 not_foundNo user with that externalId in the key's environmentImport the user first, or check the key's environment
401 invalid_sessionThe user is blockedUnblock them on the App users page if that was a mistake