Create a user via the Clerk Backend API (POST /v1/users), including password migration with password_digest

Documented steps

1. Base URL is https://api.clerk.com. Send every request with header 'Authorization: Bearer <CLERK_SECRET_KEY>' (secret key is prefixed sk_) and 'Content-Type: application/json'.
2. Check Dashboard > User & Authentication first: any identifier or field marked Required for the instance must be present in the request body or the create call is rejected.
3. POST /v1/users with a JSON body. Identifier fields are arrays: email_address: ["a@b.com"], phone_number: ["+15551234567"]. The first entry of each becomes primary.
4. Optional profile fields: username, first_name, last_name, external_id (your own system's id, useful for migrations).
5. To set a plaintext password, include password (min 8 chars; validated for strength and against breach databases).
6. To migrate an already-hashed password, send password_digest together with password_hasher (bcrypt, argon2i, argon2id, scrypt variants, pbkdf2 variants, md5, sha256, sha512 and others) instead of password.
7. Set skip_password_checks: true only when migrating plaintext passwords you cannot re-validate. Set skip_password_requirement: true to create a passwordless user.
8. Attach metadata at creation: public_metadata (backend-writable, frontend-readable), private_metadata (backend only), unsafe_metadata (writable from the frontend).
9. Set created_at (RFC3339) to backdate the signup timestamp during a migration so analytics and ordering stay correct.
10. Parse the returned User object and store id (user_xxx) plus email_addresses[] for downstream calls.
11. Handle 429 responses using the Retry-After header. Verify at https://clerk.com/docs/reference/backend/user/create-user