@faable/auth-sdk 2.7.28 → 2.7.30

package/spec/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "@faablecloud/auth",
     "description": "Auth Platform made by Faable. Manage Users and Roles",
-    "version": "2.34.0",
+    "version": "2.35.1",
     "license": {
       "name": "private",
       "url": "https://faable.com/docs/platform/privacy-policy"
@@ -2267,11 +2267,17 @@
                   "password_reset"
                 ]
               },
+              {
+                "type": "string",
+                "enum": [
+                  "import"
+                ]
+              },
               {
                 "type": "null"
               }
             ],
-            "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `null` — the field was cleared (admin un-verified the email)."
+            "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `import` — the user arrived verified from another provider through `POST /user/import` (asserted by whoever ran the migration). `null` — the field was cleared (admin un-verified the email)."
           },
           "email_verified_at": {
             "type": "string",
@@ -2293,6 +2299,11 @@
             "description": "ISO 8601 timestamp of the built-in welcome email send. Set once by the platform; guarantees at most one welcome per user.",
             "nullable": true
           },
+          "imported_at": {
+            "type": "string",
+            "description": "ISO 8601 timestamp of when the user was created by `POST /user/import`. Imported users get none of the built-in new-user emails (verification, welcome, `user.created` notifications); `user.created` webhooks still fire and carry this field.",
+            "nullable": true
+          },
           "passkey_prompted_at": {
             "type": "string",
             "description": "ISO 8601 timestamp of the last time the hosted \"create a passkey\" offer was shown to this user after a login. Drives the snooze in `login_methods.passkey_promotion_snooze_days`.",
@@ -2370,6 +2381,12 @@
                   "password_reset"
                 ]
               },
+              {
+                "type": "string",
+                "enum": [
+                  "import"
+                ]
+              },
               {
                 "type": "null"
               }
@@ -2963,7 +2980,8 @@
           "username": {
             "type": "string"
           }
-        }
+        },
+        "additionalProperties": false
       },
       "CredentialsUpdate": {
         "type": "object",
@@ -6947,7 +6965,7 @@
       },
       "ErrorCode": {
         "type": "string",
-        "description": "Machine-readable error code. One HTTP status per code.\n\n- `bad_request` (400): The request is malformed. `message` says what is wrong.\n- `validation_error` (400): The body, query or path failed schema validation. `details.issues` lists each failing field.\n- `unauthorized` (401): The request carries no valid credentials.\n- `payment_required` (402): The feature is not included in the current plan.\n- `forbidden` (403): The credentials are valid but do not allow this operation.\n- `not_found` (404): The resource does not exist in this account.\n- `method_not_allowed` (405): The HTTP method is not supported on this path.\n- `conflict` (409): The request conflicts with the current state of the resource.\n- `payload_too_large` (413): The request body exceeds the size limit.\n- `unsupported_media_type` (415): The `Content-Type` is not accepted by this endpoint.\n- `unprocessable_entity` (422): The request is well-formed but cannot be processed.\n- `too_many_requests` (429): Rate limit exceeded. Honour the `Retry-After` header.\n- `internal_error` (500): Unexpected server error. Retry later; the request id is logged.\n- `already_exists` (400): A resource with the same unique field already exists (for a user, usually `email`). `details.fields` names the field.\n- `invalid_id` (400): The id in the path is not a valid id for this resource.\n- `account_not_found` (404): No Auth Account matches the request (domain, header or token).\n- `invalid_query` (400): The `?query=` FaableQL expression could not be parsed.\n- `search_not_supported` (400): This resource does not support `?search=`.\n- `invalid_expand` (400): An `?expand=` path is not allowed on this resource.\n- `access_denied` (401): The caller may not access this row (ownership or machine-to-machine restriction).\n- `insufficient_scope` (403): The token lacks a scope this operation requires. `message` names it.\n- `team_required` (400): An Auth Account must belong to a project (team).\n- `account_limit_reached` (409): The project already has the maximum number of Auth Accounts.\n- `invalid_project_id` (400): The project id is not of the form `project_<hex>` or `team_<hex>`.\n- `account_transfer_refused` (409): The Auth Account cannot be moved to that project. `details.blockers` lists why.\n- `plan_required` (402): The setting requires a higher plan. `message` says which.\n- `not_logged_in` (401): There is no signed-in session for this request.\n- `invalid_token` (401): The bearer token is missing, malformed, expired or has no subject.\n- `not_owner` (403): The caller may only perform this operation on their own user.\n- `user_suspended` (403): The user is suspended and cannot sign in or be modified.\n- `invalid_credentials` (400): The email/username or password is incorrect.\n- `login_denied` (401): A post-login Action denied the sign-in. `message` carries the reason it gave. On token grants it is a 403 with `error: invalid_grant`.\n- `signup_denied` (403): A pre-signup Action or an active block denied the sign-up. `message` carries the reason.\n- `client_credentials_denied` (401): An Action denied the client_credentials grant. `message` carries the reason.\n- `signup_disabled` (403): Self-service sign-up is disabled on this connection.\n- `email_taken` (409): Another user in this account already uses that email.\n- `invalid_email` (400): The email address is not valid.\n- `same_email` (400): The new email is the same as the current one.\n- `user_has_no_email` (400): The operation needs an email but the user has none.\n- `password_too_weak` (400): The password does not meet the connection policy. `message` lists each unmet rule.\n- `invalid_code` (400): The verification code is wrong, expired or already used.\n- `invalid_phone` (400): The phone number is not E.164 and could not be resolved with the account default country. Include the country code.\n- `phone_changed` (400): The phone on the user changed after the code was sent. Start again.\n- `phone_already_verified` (409): The user already has a verified phone; the number cannot be swapped from the screen.\n- `sms_unavailable` (409): This account cannot send SMS right now. The suffix says why: `sms_unavailable:plan`, `:quota`, `:provider`.\n- `sms_failed` (409): The SMS provider rejected the message.\n- `invalid_state` (400): The `state` is missing, expired, or does not describe a resumable step.\n- `state_mismatch` (401): The `state` belongs to another account, session, client or ceremony.\n- `invalid_ticket` (400): The ticket does not exist or is not the kind this endpoint accepts.\n- `ticket_used` (400): The ticket was already consumed.\n- `ticket_expired` (400): The ticket is past its expiry.\n- `ticket_not_found` (404): No ticket with that id belongs to this user.\n- `credential_not_found` (404): The user has no password credential on this connection.\n- `invalid_link` (400): The magic link is malformed.\n- `expired_link` (400): The magic link token was not found or has expired.\n- `invalid_otp` (401): The one-time password is wrong or expired.\n- `invalid_client` (400): The `client_id` in the request does not name a client of this account.\n- `client_not_found` (404): No client with that `client_id`.\n- `client_mismatch` (401): The client belongs to a different account.\n- `invalid_client_metadata` (400): Dynamic client registration rejected a field (RFC 7591). `message` names it.\n- `invalid_connection` (400): The connection does not exist, is disabled, or is not of the type this flow needs.\n- `connection_required` (400): No connection was given and the client has no `default_connection`.\n- `connection_misconfigured` (400): The connection is missing settings needed to talk to its provider.\n- `passwordless_unavailable` (400): No passwordless connection is configured or enabled for this client.\n- `ambiguous_connection` (400): Several connections match; pass `connection_id`.\n- `invalid_redirect_uri` (400): The redirect URI is not registered for the client.\n- `origin_not_allowed` (403): The request `Origin` is not in the client's Allowed Web Origins.\n- `audience_not_found` (403): The `audience` does not name an API registered in this account.\n- `system_resource` (403): The resource is managed by Faable and cannot be modified or deleted.\n- `invalid_request` (400): A required OAuth parameter is missing or two of them are incompatible. `message` says which.\n- `invalid_device_code` (400): The device or user code is invalid or expired.\n- `provider_error` (400): The upstream identity provider returned an error. The suffix is the provider’s own code, when it sent one: `provider_error:bad_refresh_token` (the user must re-authorize), `provider_error:incorrect_client_credentials` (our configuration, the user can do nothing). `details.provider_error_description` carries the provider’s sentence.\n- `identity_already_linked` (409): That external identity is already linked to another user.\n- `identity_link_denied` (409): That external identity cannot be linked to this user.\n- `identity_conflict` (409): The user already has a linked identity for this connection.\n- `identity_orphaned` (400): The identity pointed at a user that no longer exists; it was removed. Sign in again.\n- `no_provider_token` (400): The identity holds no provider access token.\n- `no_refresh_token` (400): The identity holds no provider refresh token, so it cannot be refreshed.\n- `action_unavailable` (401): The Action that paused this login is disabled or belongs elsewhere.\n- `login_flow_misconfigured` (500): The login flow of this account cannot run. `message` carries the node error.\n- `mfa_required` (403): The login needs a second factor that this flow cannot collect, or one is still pending on the session.\n- `step_up_required` (403): Confirm an existing factor before changing your factors.\n- `interaction_required` (403): An Action asked for a redirect on a non-interactive flow.\n- `passkey_login_disabled` (400): Sign in with a passkey is not enabled for this client.\n- `mfa_pending` (401): A second-factor challenge is pending; answer it before continuing.\n- `mfa_invalid_code` (401): The authenticator code did not verify.\n- `mfa_invalid_recovery_code` (401): The recovery code did not verify.\n- `too_many_attempts` (429): Too many wrong codes. Wait a few minutes and try again.\n- `totp_not_allowed` (401): This account does not accept authenticator apps.\n- `no_usable_factor` (400): The user has no confirmed second factor to challenge.\n- `factor_not_found` (400): No factor with that id belongs to this user.\n- `factor_already_confirmed` (400): The factor was already confirmed.\n- `invalid_factor` (400): The factor cannot be verified (no secret material).\n- `session_missing` (401): The session that started this login no longer exists.\n- `passkey_verification_failed` (400): The WebAuthn response could not be verified.\n- `no_passkey_enrolled` (400): The user has no passkey to sign in with.\n- `malformed_credential` (400): The WebAuthn credential is malformed.\n- `unknown_passkey` (401): The passkey is not enrolled for this user.\n- `invalid_passkey` (401): The passkey assertion did not verify.\n- `invite_not_found` (404): No invite with that id in this account.\n- `invite_used` (400): The invite was already accepted.\n- `already_member` (400): The user is already a member of the team.\n- `not_a_member` (404): The user is not a member of the team.\n- `role_not_found` (404): No role with that id in this account.\n- `invalid_role` (400): The role belongs to another account.\n- `flow_not_found` (400): The login flow does not exist in this account.\n- `revision_not_found` (404): The revision is not in the flow history.",
+        "description": "Machine-readable error code. One HTTP status per code.\n\n- `bad_request` (400): The request is malformed. `message` says what is wrong.\n- `validation_error` (400): The body, query or path failed schema validation. `details.issues` lists each failing field.\n- `unauthorized` (401): The request carries no valid credentials.\n- `payment_required` (402): The feature is not included in the current plan.\n- `forbidden` (403): The credentials are valid but do not allow this operation.\n- `not_found` (404): The resource does not exist in this account.\n- `method_not_allowed` (405): The HTTP method is not supported on this path.\n- `conflict` (409): The request conflicts with the current state of the resource.\n- `payload_too_large` (413): The request body exceeds the size limit.\n- `unsupported_media_type` (415): The `Content-Type` is not accepted by this endpoint.\n- `unprocessable_entity` (422): The request is well-formed but cannot be processed.\n- `too_many_requests` (429): Rate limit exceeded. Honour the `Retry-After` header.\n- `internal_error` (500): Unexpected server error. Retry later; the request id is logged.\n- `already_exists` (400): A resource with the same unique field already exists (for a user, usually `email`). `details.fields` names the field.\n- `invalid_id` (400): The id in the path is not a valid id for this resource.\n- `account_not_found` (404): No Auth Account matches the request (domain, header or token).\n- `invalid_query` (400): The `?query=` FaableQL expression could not be parsed.\n- `search_not_supported` (400): This resource does not support `?search=`.\n- `invalid_expand` (400): An `?expand=` path is not allowed on this resource.\n- `access_denied` (401): The caller may not access this row (ownership or machine-to-machine restriction).\n- `insufficient_scope` (403): The token lacks a scope this operation requires. `message` names it.\n- `team_required` (400): An Auth Account must belong to a project (team).\n- `account_limit_reached` (409): The project already has the maximum number of Auth Accounts.\n- `invalid_project_id` (400): The project id is not of the form `project_<hex>` or `team_<hex>`.\n- `account_transfer_refused` (409): The Auth Account cannot be moved to that project. `details.blockers` lists why.\n- `plan_required` (402): The setting requires a higher plan. `message` says which.\n- `not_logged_in` (401): There is no signed-in session for this request.\n- `invalid_token` (401): The bearer token is missing, malformed, expired or has no subject.\n- `not_owner` (403): The caller may only perform this operation on their own user.\n- `user_suspended` (403): The user is suspended and cannot sign in or be modified.\n- `invalid_credentials` (400): The email/username or password is incorrect.\n- `login_denied` (401): A post-login Action denied the sign-in. `message` carries the reason it gave. On token grants it is a 403 with `error: invalid_grant`.\n- `signup_denied` (403): A pre-signup Action or an active block denied the sign-up. `message` carries the reason.\n- `client_credentials_denied` (401): An Action denied the client_credentials grant. `message` carries the reason.\n- `signup_disabled` (403): Self-service sign-up is disabled on this connection.\n- `email_taken` (409): Another user in this account already uses that email.\n- `invalid_email` (400): The email address is not valid.\n- `same_email` (400): The new email is the same as the current one.\n- `user_has_no_email` (400): The operation needs an email but the user has none.\n- `password_too_weak` (400): The password does not meet the connection policy. `message` lists each unmet rule.\n- `invalid_password_hash` (400): The imported password hash cannot be read, or its cost is above what a login can afford. `message` names the field.\n- `weak_password_hash` (400): The imported password hash uses a fast digest (MD5, SHA-1, SHA-2) or a cost below the minimum. `message` says which.\n- `invalid_code` (400): The verification code is wrong, expired or already used.\n- `invalid_phone` (400): The phone number is not E.164 and could not be resolved with the account default country. Include the country code.\n- `phone_changed` (400): The phone on the user changed after the code was sent. Start again.\n- `phone_already_verified` (409): The user already has a verified phone; the number cannot be swapped from the screen.\n- `sms_unavailable` (409): This account cannot send SMS right now. The suffix says why: `sms_unavailable:plan`, `:quota`, `:provider`.\n- `sms_failed` (409): The SMS provider rejected the message.\n- `invalid_state` (400): The `state` is missing, expired, or does not describe a resumable step.\n- `state_mismatch` (401): The `state` belongs to another account, session, client or ceremony.\n- `invalid_ticket` (400): The ticket does not exist or is not the kind this endpoint accepts.\n- `ticket_used` (400): The ticket was already consumed.\n- `ticket_expired` (400): The ticket is past its expiry.\n- `ticket_not_found` (404): No ticket with that id belongs to this user.\n- `credential_not_found` (404): The user has no password credential on this connection.\n- `invalid_link` (400): The magic link is malformed.\n- `expired_link` (400): The magic link token was not found or has expired.\n- `invalid_otp` (401): The one-time password is wrong or expired.\n- `invalid_client` (400): The `client_id` in the request does not name a client of this account.\n- `client_not_found` (404): No client with that `client_id`.\n- `client_mismatch` (401): The client belongs to a different account.\n- `invalid_client_metadata` (400): Dynamic client registration rejected a field (RFC 7591). `message` names it.\n- `invalid_connection` (400): The connection does not exist, is disabled, or is not of the type this flow needs.\n- `connection_required` (400): No connection was given and the client has no `default_connection`.\n- `connection_misconfigured` (400): The connection is missing settings needed to talk to its provider.\n- `passwordless_unavailable` (400): No passwordless connection is configured or enabled for this client.\n- `ambiguous_connection` (400): Several connections match; pass `connection_id`.\n- `invalid_redirect_uri` (400): The redirect URI is not registered for the client.\n- `origin_not_allowed` (403): The request `Origin` is not in the client's Allowed Web Origins.\n- `audience_not_found` (403): The `audience` does not name an API registered in this account.\n- `system_resource` (403): The resource is managed by Faable and cannot be modified or deleted.\n- `invalid_request` (400): A required OAuth parameter is missing or two of them are incompatible. `message` says which.\n- `invalid_device_code` (400): The device or user code is invalid or expired.\n- `provider_error` (400): The upstream identity provider returned an error. The suffix is the provider’s own code, when it sent one: `provider_error:bad_refresh_token` (the user must re-authorize), `provider_error:incorrect_client_credentials` (our configuration, the user can do nothing). `details.provider_error_description` carries the provider’s sentence.\n- `identity_already_linked` (409): That external identity is already linked to another user.\n- `identity_link_denied` (409): That external identity cannot be linked to this user.\n- `identity_conflict` (409): The user already has a linked identity for this connection.\n- `identity_orphaned` (400): The identity pointed at a user that no longer exists; it was removed. Sign in again.\n- `no_provider_token` (400): The identity holds no provider access token.\n- `no_refresh_token` (400): The identity holds no provider refresh token, so it cannot be refreshed.\n- `action_unavailable` (401): The Action that paused this login is disabled or belongs elsewhere.\n- `login_flow_misconfigured` (500): The login flow of this account cannot run. `message` carries the node error.\n- `mfa_required` (403): The login needs a second factor that this flow cannot collect, or one is still pending on the session.\n- `step_up_required` (403): Confirm an existing factor before changing your factors.\n- `interaction_required` (403): An Action asked for a redirect on a non-interactive flow.\n- `passkey_login_disabled` (400): Sign in with a passkey is not enabled for this client.\n- `mfa_pending` (401): A second-factor challenge is pending; answer it before continuing.\n- `mfa_invalid_code` (401): The authenticator code did not verify.\n- `mfa_invalid_recovery_code` (401): The recovery code did not verify.\n- `too_many_attempts` (429): Too many wrong codes. Wait a few minutes and try again.\n- `totp_not_allowed` (401): This account does not accept authenticator apps.\n- `no_usable_factor` (400): The user has no confirmed second factor to challenge.\n- `factor_not_found` (400): No factor with that id belongs to this user.\n- `factor_already_confirmed` (400): The factor was already confirmed.\n- `invalid_factor` (400): The factor cannot be verified (no secret material).\n- `session_missing` (401): The session that started this login no longer exists.\n- `passkey_verification_failed` (400): The WebAuthn response could not be verified.\n- `no_passkey_enrolled` (400): The user has no passkey to sign in with.\n- `malformed_credential` (400): The WebAuthn credential is malformed.\n- `unknown_passkey` (401): The passkey is not enrolled for this user.\n- `invalid_passkey` (401): The passkey assertion did not verify.\n- `invite_not_found` (404): No invite with that id in this account.\n- `invite_used` (400): The invite was already accepted.\n- `already_member` (400): The user is already a member of the team.\n- `not_a_member` (404): The user is not a member of the team.\n- `role_not_found` (404): No role with that id in this account.\n- `invalid_role` (400): The role belongs to another account.\n- `flow_not_found` (400): The login flow does not exist in this account.\n- `revision_not_found` (404): The revision is not in the flow history.",
         "enum": [
           "bad_request",
           "validation_error",
@@ -6989,6 +7007,8 @@
           "same_email",
           "user_has_no_email",
           "password_too_weak",
+          "invalid_password_hash",
+          "weak_password_hash",
           "invalid_code",
           "invalid_phone",
           "phone_changed",
@@ -19114,11 +19134,17 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }
                       ],
-                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `null` — the field was cleared (admin un-verified the email)."
+                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `import` — the user arrived verified from another provider through `POST /user/import` (asserted by whoever ran the migration). `null` — the field was cleared (admin un-verified the email)."
                     },
                     "email_verified_at": {
                       "type": "string",
@@ -19140,6 +19166,11 @@
                       "description": "ISO 8601 timestamp of the built-in welcome email send. Set once by the platform; guarantees at most one welcome per user.",
                       "nullable": true
                     },
+                    "imported_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of when the user was created by `POST /user/import`. Imported users get none of the built-in new-user emails (verification, welcome, `user.created` notifications); `user.created` webhooks still fire and carry this field.",
+                      "nullable": true
+                    },
                     "passkey_prompted_at": {
                       "type": "string",
                       "description": "ISO 8601 timestamp of the last time the hosted \"create a passkey\" offer was shown to this user after a login. Drives the snooze in `login_methods.passkey_promotion_snooze_days`.",
@@ -19217,6 +19248,12 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }
@@ -19668,11 +19705,17 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }
                       ],
-                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `null` — the field was cleared (admin un-verified the email)."
+                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `import` — the user arrived verified from another provider through `POST /user/import` (asserted by whoever ran the migration). `null` — the field was cleared (admin un-verified the email)."
                     },
                     "email_verified_at": {
                       "type": "string",
@@ -19694,6 +19737,11 @@
                       "description": "ISO 8601 timestamp of the built-in welcome email send. Set once by the platform; guarantees at most one welcome per user.",
                       "nullable": true
                     },
+                    "imported_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of when the user was created by `POST /user/import`. Imported users get none of the built-in new-user emails (verification, welcome, `user.created` notifications); `user.created` webhooks still fire and carry this field.",
+                      "nullable": true
+                    },
                     "passkey_prompted_at": {
                       "type": "string",
                       "description": "ISO 8601 timestamp of the last time the hosted \"create a passkey\" offer was shown to this user after a login. Drives the snooze in `login_methods.passkey_promotion_snooze_days`.",
@@ -19771,6 +19819,12 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }
@@ -20302,11 +20356,17 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }
                       ],
-                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `null` — the field was cleared (admin un-verified the email)."
+                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `import` — the user arrived verified from another provider through `POST /user/import` (asserted by whoever ran the migration). `null` — the field was cleared (admin un-verified the email)."
                     },
                     "email_verified_at": {
                       "type": "string",
@@ -20328,6 +20388,11 @@
                       "description": "ISO 8601 timestamp of the built-in welcome email send. Set once by the platform; guarantees at most one welcome per user.",
                       "nullable": true
                     },
+                    "imported_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of when the user was created by `POST /user/import`. Imported users get none of the built-in new-user emails (verification, welcome, `user.created` notifications); `user.created` webhooks still fire and carry this field.",
+                      "nullable": true
+                    },
                     "passkey_prompted_at": {
                       "type": "string",
                       "description": "ISO 8601 timestamp of the last time the hosted \"create a passkey\" offer was shown to this user after a login. Drives the snooze in `login_methods.passkey_promotion_snooze_days`.",
@@ -20405,6 +20470,12 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }
@@ -20856,11 +20927,17 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }
                       ],
-                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `null` — the field was cleared (admin un-verified the email)."
+                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `import` — the user arrived verified from another provider through `POST /user/import` (asserted by whoever ran the migration). `null` — the field was cleared (admin un-verified the email)."
                     },
                     "email_verified_at": {
                       "type": "string",
@@ -20882,6 +20959,11 @@
                       "description": "ISO 8601 timestamp of the built-in welcome email send. Set once by the platform; guarantees at most one welcome per user.",
                       "nullable": true
                     },
+                    "imported_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of when the user was created by `POST /user/import`. Imported users get none of the built-in new-user emails (verification, welcome, `user.created` notifications); `user.created` webhooks still fire and carry this field.",
+                      "nullable": true
+                    },
                     "passkey_prompted_at": {
                       "type": "string",
                       "description": "ISO 8601 timestamp of the last time the hosted \"create a passkey\" offer was shown to this user after a login. Drives the snooze in `login_methods.passkey_promotion_snooze_days`.",
@@ -20959,6 +21041,12 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }
@@ -24129,117 +24217,178 @@
         }
       }
     },
-    "/identity": {
-      "get": {
-        "operationId": "identity/list",
-        "summary": "List Identitys",
+    "/user/import": {
+      "post": {
+        "operationId": "user/import",
+        "summary": "Import users, with their password hashes",
         "tags": [
-          "identity"
+          "user"
         ],
-        "description": "List Identitys",
-        "parameters": [
-          {
-            "schema": {
-              "type": "number",
-              "minimum": 1,
-              "maximum": 200
-            },
-            "in": "query",
-            "name": "pageSize",
-            "required": false,
-            "description": "Number of items per page (max 200)"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "in": "query",
-            "name": "cursor",
-            "required": false,
-            "description": "Cursor for next page"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "in": "query",
-            "name": "next",
-            "required": false,
-            "description": "Cursor returned by the previous page"
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "in": "query",
-            "name": "user",
-            "required": false,
-            "description": "Exact match on `user`. Equivalent to `?query=user:<value>`."
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "in": "query",
-            "name": "connection",
-            "required": false,
-            "description": "Exact match on `connection`. Equivalent to `?query=connection:<value>`."
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "in": "query",
-            "name": "identity_id",
-            "required": false,
-            "description": "Exact match on `identity_id`. Equivalent to `?query=identity_id:<value>`."
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "in": "query",
-            "name": "provider",
-            "required": false,
-            "description": "Exact match on `provider`. Equivalent to `?query=provider:<value>`."
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "in": "query",
-            "name": "created_at",
-            "required": false,
-            "description": "Exact match on `created_at`. Equivalent to `?query=created_at:<value>`."
-          },
-          {
-            "schema": {
-              "type": "string"
-            },
-            "in": "query",
-            "name": "query",
-            "required": false,
-            "description": "Filter using a FaableQL query"
-          },
-          {
-            "schema": {
-              "type": "array",
-              "items": {
-                "type": "string",
-                "enum": [
-                  "user",
-                  "connection"
+        "description": "Creates up to 500 users per request, for migrations from another provider. Each row can carry a `password_hash` exported from that provider (bcrypt, scrypt, Firebase scrypt, PBKDF2, argon2): the user signs in with their existing password and the hash is upgraded to argon2id on that first login. Fast digests (MD5, SHA-1, SHA-2) and low costs are refused per row with `weak_password_hash`. Rows are matched by email, so the same file can be sent twice: existing users are `skipped` unless `update_existing`. A bad row never fails the batch: each row gets its own `status` and `error`. Imported users get none of the built-in new-user emails. The response never contains a hash, and neither does the audit log.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "users"
                 ],
-                "description": "Allowed expand paths on `identity`: `user`, `connection`."
-              },
-              "maxItems": 2
-            },
-            "in": "query",
-            "name": "expand",
-            "required": false,
-            "description": "Expand id-only fields in the response. Pass one path per entry (e.g. `?expand=user`)."
+                "properties": {
+                  "users": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "email"
+                      ],
+                      "properties": {
+                        "email": {
+                          "type": "string",
+                          "minLength": 3,
+                          "description": "The user's email."
+                        },
+                        "email_verified": {
+                          "type": "boolean",
+                          "description": "The email was verified at the previous provider. Recorded with `email_verified_method: import`."
+                        },
+                        "name": {
+                          "type": "string"
+                        },
+                        "given_name": {
+                          "type": "string"
+                        },
+                        "family_name": {
+                          "type": "string"
+                        },
+                        "phone": {
+                          "type": "string"
+                        },
+                        "birth_date": {
+                          "type": "string"
+                        },
+                        "locale": {
+                          "type": "string"
+                        },
+                        "picture": {
+                          "type": "string"
+                        },
+                        "user_metadata": {
+                          "type": "object",
+                          "properties": {},
+                          "additionalProperties": true,
+                          "description": "User Metadata"
+                        },
+                        "app_metadata": {
+                          "type": "object",
+                          "properties": {},
+                          "additionalProperties": true,
+                          "description": "App Metadata"
+                        },
+                        "password_hash": {
+                          "anyOf": [
+                            {
+                              "type": "string",
+                              "minLength": 1,
+                              "maxLength": 1024,
+                              "description": "A self-describing hash: bcrypt (`$2a$`/`$2b$`/`$2y$`), argon2 PHC (`$argon2id$…`), scrypt PHC (`$scrypt$ln=…`), PBKDF2 (`$pbkdf2-sha256$i=…` or Django `pbkdf2_sha256$…`)."
+                            },
+                            {
+                              "type": "object",
+                              "required": [
+                                "algorithm",
+                                "hash"
+                              ],
+                              "properties": {
+                                "algorithm": {
+                                  "type": "string",
+                                  "description": "`bcrypt`, `argon2id`, `argon2i`, `argon2d`, `scrypt`, `pbkdf2-sha256`, `pbkdf2-sha512` or `firebase-scrypt`."
+                                },
+                                "hash": {
+                                  "type": "string",
+                                  "minLength": 1,
+                                  "maxLength": 1024,
+                                  "description": "The hash, or its base64 digest when `salt` is given."
+                                },
+                                "salt": {
+                                  "type": "string",
+                                  "maxLength": 512,
+                                  "description": "Base64 salt."
+                                },
+                                "params": {
+                                  "type": "object",
+                                  "description": "Algorithm parameters: `iterations` (pbkdf2); `N`, `r`, `p` (scrypt); `signer_key`, `salt_separator`, `rounds`, `mem_cost` (firebase-scrypt).",
+                                  "additionalProperties": {
+                                    "anyOf": [
+                                      {
+                                        "type": "number"
+                                      },
+                                      {
+                                        "type": "string",
+                                        "maxLength": 512
+                                      }
+                                    ]
+                                  }
+                                }
+                              },
+                              "additionalProperties": false
+                            }
+                          ],
+                          "description": "A password hash exported from another provider. Verified on the first login and upgraded to argon2id. Fast digests (MD5, SHA-1, SHA-2) and low costs are refused with `weak_password_hash`."
+                        },
+                        "identities": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "required": [
+                              "connection",
+                              "identity_id"
+                            ],
+                            "properties": {
+                              "connection": {
+                                "type": "string",
+                                "description": "connection_name of the social/enterprise connection."
+                              },
+                              "identity_id": {
+                                "type": "string",
+                                "description": "The user's id at the provider (GitHub id, Google `sub`…), so their first social login finds this user instead of creating a new one."
+                              },
+                              "profile_data": {
+                                "type": "object",
+                                "description": "Provider profile, stored as-is.",
+                                "additionalProperties": {}
+                              }
+                            },
+                            "additionalProperties": false
+                          },
+                          "maxItems": 20
+                        }
+                      },
+                      "additionalProperties": false
+                    },
+                    "minItems": 1,
+                    "maxItems": 500
+                  },
+                  "connection": {
+                    "type": "string",
+                    "description": "connection_name of the database connection the password hashes go to. Defaults to the tenant database connection."
+                  },
+                  "update_existing": {
+                    "type": "boolean",
+                    "description": "Set the password hash and identities of users that already exist (matched by email) instead of skipping them. Their profile is never overwritten.",
+                    "default": false
+                  },
+                  "dry_run": {
+                    "type": "boolean",
+                    "description": "Validate every row and resolve every match without writing anything.",
+                    "default": false
+                  }
+                },
+                "additionalProperties": false
+              }
+            }
           }
-        ],
+        },
         "security": [
           {
             "bearerAuth": []
@@ -24253,34 +24402,110 @@
                 "schema": {
                   "type": "object",
                   "required": [
-                    "next",
+                    "summary",
                     "results"
                   ],
                   "properties": {
-                    "next": {
-                      "anyOf": [
-                        {
-                          "type": "string"
+                    "summary": {
+                      "type": "object",
+                      "required": [
+                        "total",
+                        "created",
+                        "updated",
+                        "skipped",
+                        "error"
+                      ],
+                      "properties": {
+                        "total": {
+                          "type": "number"
                         },
-                        {
-                          "type": "null"
+                        "created": {
+                          "type": "number"
+                        },
+                        "updated": {
+                          "type": "number"
+                        },
+                        "skipped": {
+                          "type": "number"
+                        },
+                        "error": {
+                          "type": "number"
                         }
-                      ]
+                      }
                     },
                     "results": {
                       "type": "array",
                       "items": {
-                        "$ref": "#/components/schemas/Identity"
+                        "type": "object",
+                        "required": [
+                          "index",
+                          "email",
+                          "status"
+                        ],
+                        "properties": {
+                          "index": {
+                            "type": "number",
+                            "description": "Position of the row in `users`."
+                          },
+                          "email": {
+                            "type": "string"
+                          },
+                          "status": {
+                            "anyOf": [
+                              {
+                                "type": "string",
+                                "enum": [
+                                  "created"
+                                ]
+                              },
+                              {
+                                "type": "string",
+                                "enum": [
+                                  "updated"
+                                ]
+                              },
+                              {
+                                "type": "string",
+                                "enum": [
+                                  "skipped"
+                                ]
+                              },
+                              {
+                                "type": "string",
+                                "enum": [
+                                  "error"
+                                ]
+                              }
+                            ]
+                          },
+                          "user_id": {
+                            "type": "string"
+                          },
+                          "error": {
+                            "type": "object",
+                            "required": [
+                              "code",
+                              "message"
+                            ],
+                            "properties": {
+                              "code": {
+                                "type": "string"
+                              },
+                              "message": {
+                                "type": "string"
+                              }
+                            }
+                          }
+                        }
                       }
                     }
-                  },
-                  "additionalProperties": false
+                  }
                 }
               }
             }
           },
           "400": {
-            "description": "`invalid_query` — The `?query=` FaableQL expression could not be parsed.\n\n`invalid_expand` — An `?expand=` path is not allowed on this resource.\n\n`search_not_supported` — This resource does not support `?search=`.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "description": "`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
             "content": {
               "application/json": {
                 "schema": {
@@ -24294,9 +24519,676 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
-                            "invalid_query",
-                            "invalid_expand",
-                            "search_not_supported",
+                            "validation_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "`unauthorized` — The request carries no valid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "unauthorized"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "`forbidden` — The credentials are valid but do not allow this operation.\n\n`insufficient_scope` — The token lacks a scope this operation requires. `message` names it.\n\n`user_suspended` — The user is suspended and cannot sign in or be modified.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "forbidden",
+                            "insufficient_scope",
+                            "user_suspended"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "account_not_found"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "`too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "too_many_requests"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "`internal_error` — Unexpected server error. Retry later; the request id is logged.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "internal_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/user/export": {
+      "get": {
+        "operationId": "user/export",
+        "summary": "Export users, optionally with their password hashes",
+        "tags": [
+          "user"
+        ],
+        "description": "Pages through every user of the tenant, 500 at a time, in the row shape `POST /user/import` takes. With `include_hashes` each row carries its `password_hash` (needs the `read:password_hashes` scope, is audited as `credentials.exported` and notifies its subscribers). Provider access and refresh tokens of linked identities are never exported. Available on every plan.",
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "description": "`next_cursor` of the previous page."
+          },
+          {
+            "schema": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 500,
+              "default": 500
+            },
+            "in": "query",
+            "name": "limit",
+            "required": false
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "connection",
+            "required": false,
+            "description": "connection_name of the database connection whose password hashes are exported. Defaults to the tenant database connection."
+          },
+          {
+            "schema": {
+              "type": "boolean",
+              "default": false
+            },
+            "in": "query",
+            "name": "include_hashes",
+            "required": false,
+            "description": "Include `password_hash`. Needs the `read:password_hashes` scope, is written to the audit log and notifies the `credentials.exported` subscribers."
+          }
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Default Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "users",
+                    "next_cursor",
+                    "connection"
+                  ],
+                  "properties": {
+                    "users": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "required": [
+                          "user_id",
+                          "email",
+                          "email_verified",
+                          "password_hash_status"
+                        ],
+                        "properties": {
+                          "user_id": {
+                            "type": "string"
+                          },
+                          "email": {
+                            "anyOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "type": "null"
+                              }
+                            ]
+                          },
+                          "email_verified": {
+                            "type": "boolean"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "given_name": {
+                            "type": "string"
+                          },
+                          "family_name": {
+                            "type": "string"
+                          },
+                          "phone": {
+                            "type": "string"
+                          },
+                          "birth_date": {
+                            "type": "string"
+                          },
+                          "locale": {
+                            "type": "string"
+                          },
+                          "picture": {
+                            "type": "string"
+                          },
+                          "user_metadata": {
+                            "type": "object",
+                            "additionalProperties": {}
+                          },
+                          "app_metadata": {
+                            "type": "object",
+                            "additionalProperties": {}
+                          },
+                          "password_hash_status": {
+                            "anyOf": [
+                              {
+                                "type": "string",
+                                "enum": [
+                                  "set"
+                                ]
+                              },
+                              {
+                                "type": "string",
+                                "enum": [
+                                  "not_set"
+                                ]
+                              },
+                              {
+                                "type": "string",
+                                "enum": [
+                                  "no_credential"
+                                ]
+                              },
+                              {
+                                "type": "string",
+                                "enum": [
+                                  "legacy_unexportable"
+                                ]
+                              }
+                            ],
+                            "description": "`legacy_unexportable`: the password is still stored in a pre-2026 format that is not exported; it upgrades on the next login."
+                          },
+                          "password_hash": {
+                            "type": "string",
+                            "description": "Self-describing hash (argon2id PHC for passwords set on Faable; the original format for imported ones not yet upgraded). Only with `include_hashes`."
+                          },
+                          "identities": {
+                            "type": "array",
+                            "items": {
+                              "type": "object",
+                              "required": [
+                                "connection",
+                                "identity_id"
+                              ],
+                              "properties": {
+                                "connection": {
+                                  "type": "string"
+                                },
+                                "identity_id": {
+                                  "type": "string"
+                                },
+                                "profile_data": {
+                                  "type": "object",
+                                  "additionalProperties": {}
+                                }
+                              }
+                            }
+                          }
+                        }
+                      }
+                    },
+                    "next_cursor": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "connection": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`invalid_connection` — The connection does not exist, is disabled, or is not of the type this flow needs.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "invalid_connection",
+                            "validation_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "`unauthorized` — The request carries no valid credentials.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "unauthorized"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "`forbidden` — The credentials are valid but do not allow this operation.\n\n`insufficient_scope` — The token lacks a scope this operation requires. `message` names it.\n\n`user_suspended` — The user is suspended and cannot sign in or be modified.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "forbidden",
+                            "insufficient_scope",
+                            "user_suspended"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "`account_not_found` — No Auth Account matches the request (domain, header or token).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "account_not_found"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "`too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "too_many_requests"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "500": {
+            "description": "`internal_error` — Unexpected server error. Retry later; the request id is logged.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "internal_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/identity": {
+      "get": {
+        "operationId": "identity/list",
+        "summary": "List Identitys",
+        "tags": [
+          "identity"
+        ],
+        "description": "List Identitys",
+        "parameters": [
+          {
+            "schema": {
+              "type": "number",
+              "minimum": 1,
+              "maximum": 200
+            },
+            "in": "query",
+            "name": "pageSize",
+            "required": false,
+            "description": "Number of items per page (max 200)"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "cursor",
+            "required": false,
+            "description": "Cursor for next page"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "next",
+            "required": false,
+            "description": "Cursor returned by the previous page"
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "user",
+            "required": false,
+            "description": "Exact match on `user`. Equivalent to `?query=user:<value>`."
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "connection",
+            "required": false,
+            "description": "Exact match on `connection`. Equivalent to `?query=connection:<value>`."
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "identity_id",
+            "required": false,
+            "description": "Exact match on `identity_id`. Equivalent to `?query=identity_id:<value>`."
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "provider",
+            "required": false,
+            "description": "Exact match on `provider`. Equivalent to `?query=provider:<value>`."
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "created_at",
+            "required": false,
+            "description": "Exact match on `created_at`. Equivalent to `?query=created_at:<value>`."
+          },
+          {
+            "schema": {
+              "type": "string"
+            },
+            "in": "query",
+            "name": "query",
+            "required": false,
+            "description": "Filter using a FaableQL query"
+          },
+          {
+            "schema": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "user",
+                  "connection"
+                ],
+                "description": "Allowed expand paths on `identity`: `user`, `connection`."
+              },
+              "maxItems": 2
+            },
+            "in": "query",
+            "name": "expand",
+            "required": false,
+            "description": "Expand id-only fields in the response. Pass one path per entry (e.g. `?expand=user`)."
+          }
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Default Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "next",
+                    "results"
+                  ],
+                  "properties": {
+                    "next": {
+                      "anyOf": [
+                        {
+                          "type": "string"
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ]
+                    },
+                    "results": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/Identity"
+                      }
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`invalid_query` — The `?query=` FaableQL expression could not be parsed.\n\n`invalid_expand` — An `?expand=` path is not allowed on this resource.\n\n`search_not_supported` — This resource does not support `?search=`.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "invalid_query",
+                            "invalid_expand",
+                            "search_not_supported",
                             "validation_error"
                           ]
                         }
@@ -25838,7 +26730,8 @@
                   "username": {
                     "type": "string"
                   }
-                }
+                },
+                "additionalProperties": false
               }
             }
           }
@@ -26882,20 +27775,68 @@
         "tags": [
           "credentials"
         ],
-        "description": "Sets or rotates the password for a database credential. The previous password is invalidated immediately. Records a `credential.password_changed` audit entry (initiated_by=admin) for traceability. The confirmation email is only sent when an EXISTING password is rotated: setting the first password on a credential that had none is a creation, not a change. The password is never returned.",
+        "description": "Sets or rotates the password for a database credential. Send exactly one of `password` (plaintext, hashed with argon2id) or `password_hash` (a hash exported from another provider: bcrypt, scrypt, Firebase scrypt, PBKDF2 or argon2 — verified on the first login and upgraded to argon2id). The previous password is invalidated immediately. A plaintext password records a `credential.password_changed` audit entry (initiated_by=admin); the confirmation email is only sent when an EXISTING password is rotated. An imported hash records `credential.password_imported` with its algorithm and sends no email. Neither the password nor the hash is ever returned or logged.",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
                 "type": "object",
-                "required": [
-                  "password"
-                ],
                 "properties": {
                   "password": {
                     "type": "string",
                     "description": "New plaintext password (hashed on write)."
+                  },
+                  "password_hash": {
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 1024,
+                        "description": "A self-describing hash: bcrypt (`$2a$`/`$2b$`/`$2y$`), argon2 PHC (`$argon2id$…`), scrypt PHC (`$scrypt$ln=…`), PBKDF2 (`$pbkdf2-sha256$i=…` or Django `pbkdf2_sha256$…`)."
+                      },
+                      {
+                        "type": "object",
+                        "required": [
+                          "algorithm",
+                          "hash"
+                        ],
+                        "properties": {
+                          "algorithm": {
+                            "type": "string",
+                            "description": "`bcrypt`, `argon2id`, `argon2i`, `argon2d`, `scrypt`, `pbkdf2-sha256`, `pbkdf2-sha512` or `firebase-scrypt`."
+                          },
+                          "hash": {
+                            "type": "string",
+                            "minLength": 1,
+                            "maxLength": 1024,
+                            "description": "The hash, or its base64 digest when `salt` is given."
+                          },
+                          "salt": {
+                            "type": "string",
+                            "maxLength": 512,
+                            "description": "Base64 salt."
+                          },
+                          "params": {
+                            "type": "object",
+                            "description": "Algorithm parameters: `iterations` (pbkdf2); `N`, `r`, `p` (scrypt); `signer_key`, `salt_separator`, `rounds`, `mem_cost` (firebase-scrypt).",
+                            "additionalProperties": {
+                              "anyOf": [
+                                {
+                                  "type": "number"
+                                },
+                                {
+                                  "type": "string",
+                                  "maxLength": 512
+                                }
+                              ]
+                            }
+                          }
+                        },
+                        "additionalProperties": false
+                      }
+                    ],
+                    "description": "A password hash exported from another provider. Verified on the first login and upgraded to argon2id. Fast digests (MD5, SHA-1, SHA-2) and low costs are refused with `weak_password_hash`."
                   }
                 },
                 "additionalProperties": false
@@ -26993,7 +27934,7 @@
             }
           },
           "400": {
-            "description": "`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
+            "description": "`bad_request` — The request is malformed. `message` says what is wrong.\n\n`invalid_password_hash` — The imported password hash cannot be read, or its cost is above what a login can afford. `message` names the field.\n\n`weak_password_hash` — The imported password hash uses a fast digest (MD5, SHA-1, SHA-2) or a cost below the minimum. `message` says which.\n\n`validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.",
             "content": {
               "application/json": {
                 "schema": {
@@ -27007,6 +27948,9 @@
                         "error_code": {
                           "type": "string",
                           "enum": [
+                            "bad_request",
+                            "invalid_password_hash",
+                            "weak_password_hash",
                             "validation_error"
                           ]
                         }
@@ -52677,11 +53621,17 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }
                       ],
-                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `null` — the field was cleared (admin un-verified the email)."
+                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `import` — the user arrived verified from another provider through `POST /user/import` (asserted by whoever ran the migration). `null` — the field was cleared (admin un-verified the email)."
                     },
                     "email_verified_at": {
                       "type": "string",
@@ -52703,6 +53653,11 @@
                       "description": "ISO 8601 timestamp of the built-in welcome email send. Set once by the platform; guarantees at most one welcome per user.",
                       "nullable": true
                     },
+                    "imported_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of when the user was created by `POST /user/import`. Imported users get none of the built-in new-user emails (verification, welcome, `user.created` notifications); `user.created` webhooks still fire and carry this field.",
+                      "nullable": true
+                    },
                     "passkey_prompted_at": {
                       "type": "string",
                       "description": "ISO 8601 timestamp of the last time the hosted \"create a passkey\" offer was shown to this user after a login. Drives the snooze in `login_methods.passkey_promotion_snooze_days`.",
@@ -52780,6 +53735,12 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }
@@ -53190,11 +54151,17 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }
                       ],
-                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `null` — the field was cleared (admin un-verified the email)."
+                      "description": "How `email_verified` was last set. `manual` — admin flipped the flag via `POST /user/:id`. `verification_flow` — user clicked the verification link. `passwordless_otp` — user completed passwordless OTP login. `team_invite` — user clicked a team invitation link. `email_change` — user confirmed a self-service email change. `federated` — verified by the external IdP on OAuth callback. `password_reset` — user completed the recovery link that was emailed to them (the `email` channel only). `import` — the user arrived verified from another provider through `POST /user/import` (asserted by whoever ran the migration). `null` — the field was cleared (admin un-verified the email)."
                     },
                     "email_verified_at": {
                       "type": "string",
@@ -53216,6 +54183,11 @@
                       "description": "ISO 8601 timestamp of the built-in welcome email send. Set once by the platform; guarantees at most one welcome per user.",
                       "nullable": true
                     },
+                    "imported_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of when the user was created by `POST /user/import`. Imported users get none of the built-in new-user emails (verification, welcome, `user.created` notifications); `user.created` webhooks still fire and carry this field.",
+                      "nullable": true
+                    },
                     "passkey_prompted_at": {
                       "type": "string",
                       "description": "ISO 8601 timestamp of the last time the hosted \"create a passkey\" offer was shown to this user after a login. Drives the snooze in `login_methods.passkey_promotion_snooze_days`.",
@@ -53293,6 +54265,12 @@
                             "password_reset"
                           ]
                         },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "import"
+                          ]
+                        },
                         {
                           "type": "null"
                         }