@faable/auth-sdk 2.7.19 → 2.7.21

package/dist/FaableAuthApi.d.ts

@@ -794,6 +794,7 @@ export declare class FaableAuthApi extends GeneratedFaableAuthApi {
                 visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
             } | undefined;
             login_flow?: string | null | undefined;
+            default_audience?: string | null | undefined;
             account: string;
             metadata: {
                 [key: string]: unknown;
@@ -854,6 +855,7 @@ export declare class FaableAuthApi extends GeneratedFaableAuthApi {
                 visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
             } | undefined;
             login_flow?: string | null | undefined;
+            default_audience?: string | null | undefined;
             account: string;
             metadata: {
                 [key: string]: unknown;
@@ -917,6 +919,7 @@ export declare class FaableAuthApi extends GeneratedFaableAuthApi {
                 visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
             } | undefined;
             login_flow?: string | null | undefined;
+            default_audience?: string | null | undefined;
             account: string;
             metadata: {
                 [key: string]: unknown;
@@ -979,6 +982,7 @@ export declare class FaableAuthApi extends GeneratedFaableAuthApi {
             visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
         } | undefined;
         login_flow?: string | null | undefined;
+        default_audience?: string | null | undefined;
         account: string;
         metadata: {
             [key: string]: unknown;

package/dist/api/generated-client.d.ts

@@ -1241,6 +1241,7 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
             visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
         } | undefined;
         login_flow?: string | null | undefined;
+        default_audience?: string | null | undefined;
         account: string;
         metadata: {
             [key: string]: unknown;
@@ -1317,6 +1318,7 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
             visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
         } | undefined;
         login_flow?: string | null | undefined;
+        default_audience?: string | null | undefined;
         account: string;
         metadata: {
             [key: string]: unknown;
@@ -1394,6 +1396,7 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
             visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
         } | undefined;
         login_flow?: string | null | undefined;
+        default_audience?: string | null | undefined;
         account: string;
         metadata: {
             [key: string]: unknown;
@@ -1472,6 +1475,7 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
                 visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
             } | undefined;
             login_flow?: string | null | undefined;
+            default_audience?: string | null | undefined;
             account: string;
             metadata: {
                 [key: string]: unknown;
@@ -1532,6 +1536,7 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
                 visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
             } | undefined;
             login_flow?: string | null | undefined;
+            default_audience?: string | null | undefined;
             account: string;
             metadata: {
                 [key: string]: unknown;
@@ -1595,6 +1600,7 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
                 visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
             } | undefined;
             login_flow?: string | null | undefined;
+            default_audience?: string | null | undefined;
             account: string;
             metadata: {
                 [key: string]: unknown;
@@ -1674,6 +1680,7 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
             visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
         } | undefined;
         login_flow?: string | null | undefined;
+        default_audience?: string | null | undefined;
         account: string;
         metadata: {
             [key: string]: unknown;
@@ -1751,6 +1758,7 @@ export declare abstract class GeneratedFaableAuthApi extends FaableApi {
             visible?: ("email" | "sms" | "whatsapp" | "factor")[] | undefined;
         } | undefined;
         login_flow?: string | null | undefined;
+        default_audience?: string | null | undefined;
         account: string;
         metadata: {
             [key: string]: unknown;

package/dist/api/types.d.ts

@@ -3665,7 +3665,11 @@ export interface paths {
         delete?: never;
         options?: never;
         head?: never;
-        patch?: never;
+        /**
+         * Update current User profile
+         * @description Updates the profile of the User behind the current session or bearer token. Only `name`, `company_name` and `country_iso` can be changed; `company_name` is merged into `user_metadata` without touching its other keys. A Bearer token must belong to this Account.
+         */
+        patch: operations["session/me_update"];
         trace?: never;
     };
     "/logout": {
@@ -4546,6 +4550,8 @@ export interface components {
             };
             /** @description A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit. */
             login_flow?: string | null;
+            /** @description Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`. */
+            default_audience?: string | null;
             /** @description Object is related with this account */
             account: string;
             /**
@@ -4657,6 +4663,8 @@ export interface components {
                 visible?: ("email" | "sms" | "whatsapp" | "factor")[];
             } | null;
             login_flow?: string | null;
+            /** @description Audience a client_credentials token request gets when it sends none. An explicit `audience` wins. `null` removes it. */
+            default_audience?: string | null;
             /**
              * @description Free-form client metadata. Replaces the whole object — send the full merged value, not a partial delta.
              * @default {}
@@ -9522,6 +9530,8 @@ export interface operations {
                         };
                         /** @description A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit. */
                         login_flow?: string | null;
+                        /** @description Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`. */
+                        default_audience?: string | null;
                         /** @description Object is related with this account */
                         account: string;
                         /**
@@ -9716,6 +9726,8 @@ export interface operations {
                         };
                         /** @description A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit. */
                         login_flow?: string | null;
+                        /** @description Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`. */
+                        default_audience?: string | null;
                         /** @description Object is related with this account */
                         account: string;
                         /**
@@ -9907,6 +9919,8 @@ export interface operations {
                         visible?: ("email" | "sms" | "whatsapp" | "factor")[];
                     } | null;
                     login_flow?: string | null;
+                    /** @description Audience a client_credentials token request gets when it sends none. An explicit `audience` wins. `null` removes it. */
+                    default_audience?: string | null;
                     /**
                      * @description Free-form client metadata. Replaces the whole object — send the full merged value, not a partial delta.
                      * @default {}
@@ -10001,6 +10015,8 @@ export interface operations {
                         };
                         /** @description A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit. */
                         login_flow?: string | null;
+                        /** @description Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`. */
+                        default_audience?: string | null;
                         /** @description Object is related with this account */
                         account: string;
                         /**
@@ -10201,6 +10217,8 @@ export interface operations {
                         };
                         /** @description A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit. */
                         login_flow?: string | null;
+                        /** @description Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`. */
+                        default_audience?: string | null;
                         /** @description Object is related with this account */
                         account: string;
                         /**
@@ -10399,6 +10417,8 @@ export interface operations {
                         };
                         /** @description A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit. */
                         login_flow?: string | null;
+                        /** @description Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`. */
+                        default_audience?: string | null;
                         /** @description Object is related with this account */
                         account: string;
                         /**
@@ -24053,6 +24073,237 @@ export interface operations {
             };
         };
     };
+    "session/me_update": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** @description Profile fields the current User may edit on themselves. `company_name` is stored in `user_metadata`, merged with whatever else is there. */
+        requestBody: {
+            content: {
+                "application/json": {
+                    name?: string;
+                    company_name?: string;
+                    country_iso?: string;
+                };
+            };
+        };
+        responses: {
+            /** @description The current User. With a Bearer access token the response also carries the token's custom claims (e.g. `ciapol.com/station_id`) as top-level properties; profile fields always win over a same-named claim. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        /** @description User ID */
+                        id: string;
+                        /** @description User name */
+                        name?: string | null;
+                        /** @description unique username for this user */
+                        username?: string | null;
+                        /** @description Given name */
+                        given_name?: string | null;
+                        /** @description Family name */
+                        family_name?: string | null;
+                        /** @description Middle name (OIDC §5.1) */
+                        middle_name?: string | null;
+                        /** @description Casual name. Distinct from given_name (e.g. "Mike" vs "Michael"). OIDC §5.1 */
+                        nickname?: string | null;
+                        /** @description User email */
+                        email?: string | null;
+                        /**
+                         * @description true if email is verified
+                         * @default false
+                         */
+                        email_verified: boolean;
+                        /** @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). */
+                        email_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | "sms_otp" | "password_reset" | null;
+                        /** @description ISO 8601 timestamp of when `email_verified` was last flipped to true. */
+                        email_verified_at?: string | null;
+                        /** @description ISO 8601 timestamp of the user's last verified email change. When set, OAuth callbacks will not overwrite `email`/`email_verified` from the federated provider — the manually-chosen email wins. */
+                        email_change_locked_at?: string | null;
+                        /** @description ISO 8601 timestamp of the last Postmark hard bounce / spam complaint for this address. When set, the email is treated as undeliverable and no further emails are sent to the user until the address changes. */
+                        email_bounced_at?: string | null;
+                        /** @description ISO 8601 timestamp of the built-in welcome email send. Set once by the platform; guarantees at most one welcome per user. */
+                        welcome_sent_at?: string | null;
+                        /** @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`. */
+                        passkey_prompted_at?: string | null;
+                        /** @description How many times the passkey offer has been shown to this user. Capped by `login_methods.passkey_promotion_max_prompts`; reset by an administrator through `POST /user/:id/passkey-prompt/reset`. */
+                        passkey_prompt_count?: number;
+                        /** @description ISO 8601 timestamp of the last time the user chose "Not now" on the passkey offer, as opposed to closing the tab. */
+                        passkey_prompt_dismissed_at?: string | null;
+                        /** @description contact phone number */
+                        phone?: string | null;
+                        /** @description Whether `phone` is a valid E.164 number. Calculated on read, never stored: new writes are rejected unless they normalise, so a `false` here is a legacy row that no SMS can reach — fix the number, or set the account default country and write it again. */
+                        phone_e164?: boolean;
+                        /** @description phone is verified */
+                        phone_verified: boolean;
+                        /** @description How `phone_verified` was last set. Same enum as `email_verified_method`, plus `sms_otp` — the user typed a code sent by SMS (`POST /user/:id/verify-phone/start`). */
+                        phone_verified_method?: "manual" | "verification_flow" | "passwordless_otp" | "team_invite" | "email_change" | "federated" | "sms_otp" | "password_reset" | null;
+                        /** @description ISO 8601 timestamp of when `phone_verified` was last flipped to true. */
+                        phone_verified_at?: string | null;
+                        /** @description country iso code */
+                        country_iso?: string | null;
+                        /** @description user birth_date */
+                        birth_date?: string | null;
+                        /** @description User gender (free-form, OIDC §5.1) */
+                        gender?: string | null;
+                        /** @description IANA time-zone name (e.g. "Europe/Madrid"). OIDC §5.1 — used for the `zoneinfo` claim. */
+                        zoneinfo?: string | null;
+                        /** @description user main language */
+                        locale?: string | null;
+                        /** @description customer region */
+                        region?: string | null;
+                        /** @description URL of the User's personal Web page or blog (OIDC §5.1) */
+                        website?: string | null;
+                        address?: {
+                            /** @description Full mailing address, formatted for display (may contain newlines) */
+                            formatted?: string | null;
+                            street_address?: string | null;
+                            /** @description City or locality */
+                            locality?: string | null;
+                            /** @description State, province, or region */
+                            region?: string | null;
+                            postal_code?: string | null;
+                            /** @description Country name */
+                            country?: string | null;
+                        } | null;
+                        /** @description User picture url */
+                        picture?: string | null;
+                        /** @description Total number of logins this user has performed. */
+                        logins_count: number;
+                        /** @description Last IP address from which this user logged in */
+                        last_ip?: string | null;
+                        /** @description Last date and time this user logged in (ISO_8601 format) */
+                        last_login?: string | null;
+                        /** @description Primary Accept-Language subtag seen at this user's FIRST login (e.g. "zh"). Written once and never updated, so a later login whose language differs is visible as `event.stats.language_changed` in actions — a cross-session signal no single request can produce. */
+                        first_language?: string | null;
+                        /**
+                         * @description true while the user is suspended. A suspended user is rejected at every login flow, token grant, session use and management-API call.
+                         * @default false
+                         */
+                        suspended: boolean;
+                        /** @description ISO 8601 timestamp of when `suspended` was last flipped to true. */
+                        suspended_at?: string | null;
+                        /** @description Free-form reason recorded when the user was suspended (e.g. "abuse: RCE payload"). */
+                        suspended_reason?: string | null;
+                        /**
+                         * @description User Metadata
+                         * @default {}
+                         */
+                        user_metadata: {
+                            [key: string]: unknown;
+                        };
+                        /**
+                         * @description App Metadata
+                         * @default {}
+                         */
+                        app_metadata: {
+                            [key: string]: unknown;
+                        };
+                        /** @description Object is related with this account */
+                        account: string;
+                        /**
+                         * @description UserMetadata
+                         * @default {}
+                         */
+                        metadata: {
+                            [key: string]: unknown;
+                        };
+                        /** @description User creation date */
+                        createdAt: string;
+                        /** @description User updated date */
+                        updatedAt?: string;
+                    } & {
+                        [key: string]: unknown;
+                    };
+                };
+            };
+            /**
+             * @description `bad_request` — The request is malformed. `message` says what is wrong.
+             *
+             *     `validation_error` — The body, query or path failed schema validation. `details.issues` lists each failing field.
+             */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"] & {
+                        /** @enum {string} */
+                        error_code?: "bad_request" | "validation_error";
+                    };
+                };
+            };
+            /**
+             * @description `mfa_pending` — A second-factor challenge is pending; answer it before continuing.
+             *
+             *     `not_logged_in` — There is no signed-in session for this request.
+             */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"] & {
+                        /** @enum {string} */
+                        error_code?: "mfa_pending" | "not_logged_in";
+                    };
+                };
+            };
+            /** @description `forbidden` — The credentials are valid but do not allow this operation. */
+            403: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"] & {
+                        /** @enum {string} */
+                        error_code?: "forbidden";
+                    };
+                };
+            };
+            /** @description `account_not_found` — No Auth Account matches the request (domain, header or token). */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"] & {
+                        /** @enum {string} */
+                        error_code?: "account_not_found";
+                    };
+                };
+            };
+            /** @description `too_many_requests` — Rate limit exceeded. Honour the `Retry-After` header. */
+            429: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"] & {
+                        /** @enum {string} */
+                        error_code?: "too_many_requests";
+                    };
+                };
+            };
+            /** @description `internal_error` — Unexpected server error. Retry later; the request id is logged. */
+            500: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"] & {
+                        /** @enum {string} */
+                        error_code?: "internal_error";
+                    };
+                };
+            };
+        };
+    };
     "session/logout": {
         parameters: {
             query?: {

package/dist/version.js

@@ -9,13 +9,13 @@
 // login pages could not import the SDK at all. Same pattern as auth-js.
 //
 // The sentinels MUST stay byte-identical to the `from` values in `.releaserc`.
-export const version = "2.7.19";
+export const version = "2.7.21";
 // Short git SHA of the released commit. The version dates a build; this names
 // the exact tree, so a canonical log line or an audit entry leads straight to
 // `git show <sha>`. Deliberately NOT hex: an unreleased build (dev, a local
 // link) cannot be mistaken for a real commit — auth only records values that
 // look like a SHA, and this one never will.
-export const commit = "0d99110";
+export const commit = "eda9c4d";
 // What this SDK writes in `x-faable-client`. Exported for a consumer that
 // builds a strategy on its own (outside `FaableAuthApi`) and still wants the
 // token request attributed — a bare `authClientCredentials` stamps only what

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faable/auth-sdk",
-  "version": "2.7.19",
+  "version": "2.7.21",
   "author": "Marc Pomar <marc@faable.com>",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/spec/openapi.json

@@ -3,7 +3,7 @@
   "info": {
     "title": "@faablecloud/auth",
     "description": "Auth Platform made by Faable. Manage Users and Roles",
-    "version": "2.27.2",
+    "version": "2.31.0",
     "license": {
       "name": "private",
       "url": "https://faable.com/docs/platform/privacy-policy"
@@ -1657,6 +1657,11 @@
             ],
             "description": "A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit."
           },
+          "default_audience": {
+            "type": "string",
+            "description": "Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`.",
+            "nullable": true
+          },
           "account": {
             "type": "string",
             "description": "Object is related with this account"
@@ -2131,6 +2136,12 @@
               }
             ]
           },
+          "default_audience": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Audience a client_credentials token request gets when it sends none. An explicit `audience` wins. `null` removes it.",
+            "nullable": true
+          },
           "metadata": {
             "type": "object",
             "properties": {},
@@ -15735,6 +15746,11 @@
                       ],
                       "description": "A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit."
                     },
+                    "default_audience": {
+                      "type": "string",
+                      "description": "Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`.",
+                      "nullable": true
+                    },
                     "account": {
                       "type": "string",
                       "description": "Object is related with this account"
@@ -16342,6 +16358,11 @@
                       ],
                       "description": "A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit."
                     },
+                    "default_audience": {
+                      "type": "string",
+                      "description": "Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`.",
+                      "nullable": true
+                    },
                     "account": {
                       "type": "string",
                       "description": "Object is related with this account"
@@ -16934,6 +16955,12 @@
                       }
                     ]
                   },
+                  "default_audience": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Audience a client_credentials token request gets when it sends none. An explicit `audience` wins. `null` removes it.",
+                    "nullable": true
+                  },
                   "metadata": {
                     "type": "object",
                     "properties": {},
@@ -17367,6 +17394,11 @@
                       ],
                       "description": "A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit."
                     },
+                    "default_audience": {
+                      "type": "string",
+                      "description": "Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`.",
+                      "nullable": true
+                    },
                     "account": {
                       "type": "string",
                       "description": "Object is related with this account"
@@ -17974,6 +18006,11 @@
                       ],
                       "description": "A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit."
                     },
+                    "default_audience": {
+                      "type": "string",
+                      "description": "Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`.",
+                      "nullable": true
+                    },
                     "account": {
                       "type": "string",
                       "description": "Object is related with this account"
@@ -18582,6 +18619,11 @@
                       ],
                       "description": "A login flow bound to this client (`loginflow_xxx`), overriding the account's. Absent = inherit."
                     },
+                    "default_audience": {
+                      "type": "string",
+                      "description": "Audience used when a client_credentials token request sends none (e.g. `faable:management:<account_id>`). An explicit `audience` in the request wins. Absent = `${iss}/userinfo`.",
+                      "nullable": true
+                    },
                     "account": {
                       "type": "string",
                       "description": "Object is related with this account"
@@ -53031,6 +53073,570 @@
             }
           }
         }
+      },
+      "patch": {
+        "operationId": "session/me_update",
+        "summary": "Update current User profile",
+        "tags": [
+          "session"
+        ],
+        "description": "Updates the profile of the User behind the current session or bearer token. Only `name`, `company_name` and `country_iso` can be changed; `company_name` is merged into `user_metadata` without touching its other keys. A Bearer token must belong to this Account.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 100
+                  },
+                  "company_name": {
+                    "type": "string",
+                    "maxLength": 100
+                  },
+                  "country_iso": {
+                    "type": "string",
+                    "maxLength": 3
+                  }
+                },
+                "additionalProperties": false,
+                "description": "Profile fields the current User may edit on themselves. `company_name` is stored in `user_metadata`, merged with whatever else is there."
+              }
+            }
+          },
+          "description": "Profile fields the current User may edit on themselves. `company_name` is stored in `user_metadata`, merged with whatever else is there."
+        },
+        "responses": {
+          "200": {
+            "description": "The current User. With a Bearer access token the response also carries the token's custom claims (e.g. `ciapol.com/station_id`) as top-level properties; profile fields always win over a same-named claim.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "id",
+                    "email_verified",
+                    "phone_verified",
+                    "logins_count",
+                    "user_metadata",
+                    "app_metadata",
+                    "account",
+                    "createdAt"
+                  ],
+                  "properties": {
+                    "id": {
+                      "type": "string",
+                      "description": "User ID"
+                    },
+                    "name": {
+                      "type": "string",
+                      "description": "User name",
+                      "nullable": true
+                    },
+                    "username": {
+                      "type": "string",
+                      "description": "unique username for this user",
+                      "nullable": true
+                    },
+                    "given_name": {
+                      "type": "string",
+                      "description": "Given name",
+                      "nullable": true
+                    },
+                    "family_name": {
+                      "type": "string",
+                      "description": "Family name",
+                      "nullable": true
+                    },
+                    "middle_name": {
+                      "type": "string",
+                      "description": "Middle name (OIDC §5.1)",
+                      "nullable": true
+                    },
+                    "nickname": {
+                      "type": "string",
+                      "description": "Casual name. Distinct from given_name (e.g. \"Mike\" vs \"Michael\"). OIDC §5.1",
+                      "nullable": true
+                    },
+                    "email": {
+                      "type": "string",
+                      "description": "User email",
+                      "nullable": true
+                    },
+                    "email_verified": {
+                      "type": "boolean",
+                      "description": "true if email is verified",
+                      "default": false
+                    },
+                    "email_verified_method": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "enum": [
+                            "manual"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "verification_flow"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "passwordless_otp"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "team_invite"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "email_change"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "federated"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "sms_otp"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "password_reset"
+                          ]
+                        },
+                        {
+                          "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)."
+                    },
+                    "email_verified_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of when `email_verified` was last flipped to true.",
+                      "nullable": true
+                    },
+                    "email_change_locked_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of the user's last verified email change. When set, OAuth callbacks will not overwrite `email`/`email_verified` from the federated provider — the manually-chosen email wins.",
+                      "nullable": true
+                    },
+                    "email_bounced_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of the last Postmark hard bounce / spam complaint for this address. When set, the email is treated as undeliverable and no further emails are sent to the user until the address changes.",
+                      "nullable": true
+                    },
+                    "welcome_sent_at": {
+                      "type": "string",
+                      "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
+                    },
+                    "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`.",
+                      "nullable": true
+                    },
+                    "passkey_prompt_count": {
+                      "type": "integer",
+                      "description": "How many times the passkey offer has been shown to this user. Capped by `login_methods.passkey_promotion_max_prompts`; reset by an administrator through `POST /user/:id/passkey-prompt/reset`."
+                    },
+                    "passkey_prompt_dismissed_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of the last time the user chose \"Not now\" on the passkey offer, as opposed to closing the tab.",
+                      "nullable": true
+                    },
+                    "phone": {
+                      "type": "string",
+                      "description": "contact phone number",
+                      "nullable": true
+                    },
+                    "phone_e164": {
+                      "type": "boolean",
+                      "description": "Whether `phone` is a valid E.164 number. Calculated on read, never stored: new writes are rejected unless they normalise, so a `false` here is a legacy row that no SMS can reach — fix the number, or set the account default country and write it again."
+                    },
+                    "phone_verified": {
+                      "type": "boolean",
+                      "description": "phone is verified"
+                    },
+                    "phone_verified_method": {
+                      "anyOf": [
+                        {
+                          "type": "string",
+                          "enum": [
+                            "manual"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "verification_flow"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "passwordless_otp"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "team_invite"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "email_change"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "federated"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "sms_otp"
+                          ]
+                        },
+                        {
+                          "type": "string",
+                          "enum": [
+                            "password_reset"
+                          ]
+                        },
+                        {
+                          "type": "null"
+                        }
+                      ],
+                      "description": "How `phone_verified` was last set. Same enum as `email_verified_method`, plus `sms_otp` — the user typed a code sent by SMS (`POST /user/:id/verify-phone/start`)."
+                    },
+                    "phone_verified_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of when `phone_verified` was last flipped to true.",
+                      "nullable": true
+                    },
+                    "country_iso": {
+                      "type": "string",
+                      "description": "country iso code",
+                      "nullable": true
+                    },
+                    "birth_date": {
+                      "type": "string",
+                      "description": "user birth_date",
+                      "nullable": true
+                    },
+                    "gender": {
+                      "type": "string",
+                      "description": "User gender (free-form, OIDC §5.1)",
+                      "nullable": true
+                    },
+                    "zoneinfo": {
+                      "type": "string",
+                      "description": "IANA time-zone name (e.g. \"Europe/Madrid\"). OIDC §5.1 — used for the `zoneinfo` claim.",
+                      "nullable": true
+                    },
+                    "locale": {
+                      "type": "string",
+                      "description": "user main language",
+                      "nullable": true
+                    },
+                    "region": {
+                      "type": "string",
+                      "description": "customer region",
+                      "nullable": true
+                    },
+                    "website": {
+                      "type": "string",
+                      "description": "URL of the User's personal Web page or blog (OIDC §5.1)",
+                      "nullable": true
+                    },
+                    "address": {
+                      "type": "object",
+                      "properties": {
+                        "formatted": {
+                          "type": "string",
+                          "description": "Full mailing address, formatted for display (may contain newlines)",
+                          "nullable": true
+                        },
+                        "street_address": {
+                          "type": "string",
+                          "nullable": true
+                        },
+                        "locality": {
+                          "type": "string",
+                          "description": "City or locality",
+                          "nullable": true
+                        },
+                        "region": {
+                          "type": "string",
+                          "description": "State, province, or region",
+                          "nullable": true
+                        },
+                        "postal_code": {
+                          "type": "string",
+                          "nullable": true
+                        },
+                        "country": {
+                          "type": "string",
+                          "description": "Country name",
+                          "nullable": true
+                        }
+                      },
+                      "additionalProperties": false,
+                      "nullable": true
+                    },
+                    "picture": {
+                      "type": "string",
+                      "description": "User picture url",
+                      "nullable": true
+                    },
+                    "logins_count": {
+                      "type": "number",
+                      "description": "Total number of logins this user has performed."
+                    },
+                    "last_ip": {
+                      "type": "string",
+                      "description": "Last IP address from which this user logged in",
+                      "nullable": true
+                    },
+                    "last_login": {
+                      "type": "string",
+                      "description": "Last date and time this user logged in (ISO_8601 format)",
+                      "nullable": true
+                    },
+                    "first_language": {
+                      "type": "string",
+                      "description": "Primary Accept-Language subtag seen at this user's FIRST login (e.g. \"zh\"). Written once and never updated, so a later login whose language differs is visible as `event.stats.language_changed` in actions — a cross-session signal no single request can produce.",
+                      "nullable": true
+                    },
+                    "suspended": {
+                      "type": "boolean",
+                      "description": "true while the user is suspended. A suspended user is rejected at every login flow, token grant, session use and management-API call.",
+                      "default": false
+                    },
+                    "suspended_at": {
+                      "type": "string",
+                      "description": "ISO 8601 timestamp of when `suspended` was last flipped to true.",
+                      "nullable": true
+                    },
+                    "suspended_reason": {
+                      "type": "string",
+                      "description": "Free-form reason recorded when the user was suspended (e.g. \"abuse: RCE payload\").",
+                      "nullable": true
+                    },
+                    "user_metadata": {
+                      "type": "object",
+                      "properties": {},
+                      "additionalProperties": true,
+                      "description": "User Metadata",
+                      "default": {}
+                    },
+                    "app_metadata": {
+                      "type": "object",
+                      "properties": {},
+                      "additionalProperties": true,
+                      "description": "App Metadata",
+                      "default": {}
+                    },
+                    "account": {
+                      "type": "string",
+                      "description": "Object is related with this account"
+                    },
+                    "metadata": {
+                      "type": "object",
+                      "properties": {},
+                      "additionalProperties": true,
+                      "description": "UserMetadata",
+                      "default": {}
+                    },
+                    "createdAt": {
+                      "type": "string",
+                      "description": "User creation date"
+                    },
+                    "updatedAt": {
+                      "type": "string",
+                      "description": "User updated date"
+                    }
+                  },
+                  "additionalProperties": true,
+                  "description": "The current User. With a Bearer access token the response also carries the token's custom claims (e.g. `ciapol.com/station_id`) as top-level properties; profile fields always win over a same-named claim."
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "`bad_request` — The request is malformed. `message` says what is wrong.\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": [
+                            "bad_request",
+                            "validation_error"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "`mfa_pending` — A second-factor challenge is pending; answer it before continuing.\n\n`not_logged_in` — There is no signed-in session for this request.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "mfa_pending",
+                            "not_logged_in"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "`forbidden` — The credentials are valid but do not allow this operation.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "allOf": [
+                    {
+                      "$ref": "#/components/schemas/ErrorResponse"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "error_code": {
+                          "type": "string",
+                          "enum": [
+                            "forbidden"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "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"
+                          ]
+                        }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
       }
     },
     "/logout": {