[Do not merge] doc: Update docs for canonical OAuth field names

authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/adfs.md

@@ -6,7 +6,7 @@
 2. Create an application in your AD FS Server, obtain "Client ID", "Client Secret" and "Discovery Document Endpoint". Discovery Document Endpoint typically ends with `/.well-known/openid-configuration`. Configure your application with redirect uri `https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/adfs`.
 
 {% hint style="info" %}
-Redirect URI has the form of `/sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal.
+Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal.
 {% endhint %}
 
 ## Configure Sign in with Microsoft AD FS through the portal

authentication-and-access/social-enterprise-login-providers/enterprise-login-providers/azureadv2.md

@@ -16,7 +16,7 @@
 6. Follow [this](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#add-a-client-secret) section to add a client secret. Remember to record the secret value when you add the client secret, as it will not be displayed again. This will be needed for configure OAuth client in Authgear.
 
 {% hint style="info" %}
-Redirect URI has the form of `/sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal.
+Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal.
 {% endhint %}
 
 ## Configure Sign in with Microsoft through the portal

authentication-and-access/social-enterprise-login-providers/social-login-providers/apple.md

@@ -18,7 +18,7 @@ To configure "Sign in with Apple" for Authgear, you will need to fulfil the foll
 10. Create a "Key" following [this guide](https://developer.apple.com/help/account/manage-keys/create-a-private-key) with "Sign in with Apple" enabled. Click "Configure" next to "Sign in with Apple" and select "Primary App ID" with app ID created above. Keep the private key safe, you need to provide this later.
 
 {% hint style="info" %}
-Redirect URI has the form of `/sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal.
+Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal.
 {% endhint %}
 
 ## Configure Sign in with Apple in Authgear Portal

authentication-and-access/social-enterprise-login-providers/social-login-providers/facebook.md

@@ -44,7 +44,7 @@ Follow the on-screen instructions to finish the app creation process.
 <figure><img src="../../../.gitbook/assets/image (2).png" alt=""><figcaption></figcaption></figure>
 
 {% hint style="info" %}
-Redirect URI has the form of `https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal.
+Redirect URI has the form of `https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal.
 
 See [Your Authgear Endpoint](../../../reference/glossary.md#your-authgear-endpoint) for instructions on how to get the value for `YOUR_AUTHGEAR_ENDPOINT`.
 {% endhint %}

authentication-and-access/social-enterprise-login-providers/social-login-providers/google.md

@@ -28,7 +28,7 @@ After creating a new project, you will need to configure the OAuth consent scree
 ![OAuth Client ID in the Credentials page](../../../.gitbook/assets/GCP_create_client_id.png)
 
 {% hint style="info" %}
-Redirect URI has the form of `/sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal.
+Redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal.
 {% endhint %}
 
 You can find more details in [official Google Cloud Platform doc](https://support.google.com/cloud/answer/6158849)

authentication-and-access/social-enterprise-login-providers/social-login-providers/linkedin.md

@@ -20,7 +20,7 @@ Also, add `https://<YOUR_AUTHGEAR_ENDPOINT>/sso/oauth2/callback/linkedin` to "Au
 <figure><img src="../../../.gitbook/assets/linkedin-social-login-auth-tab.png" alt=""><figcaption><p>LinkedIn app, "Auth" tab</p></figcaption></figure>
 
 {% hint style="info" %}
-The redirect URI has the form of `/sso/oauth2/callback/:alias`. The `alias` is used as the identifier of OAuth provider. You can configure the `alias` in Authgear Portal
+The redirect URI has the form of `/sso/oauth2/callback/:oauth_provider_alias`. The `oauth_provider_alias` is the OAuth Provider Alias configured for this provider in Authgear Portal
 {% endhint %}
 
 Next, open the **Products** tab of your LinkedIn app, and request access to "Sign In with LinkedIn using OpenID Connect."

customization/ui-customization/custom-ui/authentication-flow-api.md

@@ -60,8 +60,8 @@ The following is a sample of the response you would get from the Authentication
                     },
                     {
                         "identification": "oauth",
-                        "provider_type": "google",
-                        "alias": "google"
+                        "oauth_provider_type": "google",
+                        "oauth_provider_alias": "google"
                     }
                 ]
             }

reference/apis/authentication-flow-api.md

@@ -438,13 +438,13 @@ When you make the above HTTP request to create a signup flow, you get a response
           },
           {
             "identification": "oauth",
-            "provider_type": "google",
-            "alias": "google"
+            "oauth_provider_type": "google",
+            "oauth_provider_alias": "google"
           },
           {
             "identification": "oauth",
-            "provider_type": "wechat",
-            "alias": "wechat_mobile",
+            "oauth_provider_type": "wechat",
+            "oauth_provider_alias": "wechat_mobile",
             "wechat_app_type": "mobile"
           }
         ]
@@ -545,8 +545,8 @@ The response for the above HTTP request will look like this:
                     },
                     {
                         "identification": "oauth",
-                        "provider_type": "wechat",
-                        "alias": "wechat_mobile",
+                        "oauth_provider_type": "wechat",
+                        "oauth_provider_alias": "wechat_mobile",
                         "wechat_app_type": "mobile"
                     }
                 ]
@@ -884,12 +884,12 @@ Presence in response:
 ```
 {
   "identification": "oauth",
-  "provider_type": "google",
-  "alias": "google"
+  "oauth_provider_type": "google",
+  "oauth_provider_alias": "google"
 }
 ```
 
-* `provider_type`: The expected value here is a keyword for a specific OAuth provider. Possible values are:
+* `oauth_provider_type`: The type of OAuth provider. Possible values are:
   * `google`
   * `facebook`
   * `github`
@@ -899,7 +899,7 @@ Presence in response:
   * `adfs`
   * `apple`
   * `wechat`
-* `alias`: The identifier of the OAuth provider. You pass this in the input.
+* `oauth_provider_alias`: The configured alias of the OAuth provider. Pass this value as `alias` in the input.
 
 Usage in input:
 
@@ -923,8 +923,8 @@ The response to an Authentication Flow API request with the above input should l
             "type": "identify",
             "identification": "oauth",
             "data": {
-                "alias": "google",
                 "oauth_provider_type": "google",
+                "oauth_provider_alias": "google",
                 "oauth_authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=850158775140-cuov06p5ru3kq27n4bfvrlp3fb7vrpgd.apps.googleusercontent.com&prompt=select_account&redirect_uri=http%3A%2F%2Flocalhost%3A3000&response_type=code&scope=openid+profile+email"
             }
         }

reference/apis/oauth-2.0-and-openid-connect-oidc/userinfo.md

@@ -32,6 +32,22 @@ The following code shows an example of the structure and some information that's
     "given_name": "Doe",
     "phone_number": "0805551112",
     "phone_number_verified": true,
+    "https://authgear.com/claims/user/identities": [
+      {
+        "type": "login_id",
+        "created_at": "2025-06-04T10:50:00.000000Z",
+        "updated_at": "2025-06-04T10:50:00.000000Z",
+        "login_id_key": "email",
+        "login_id_type": "email"
+      },
+      {
+        "type": "oauth",
+        "created_at": "2025-06-04T10:52:00.000000Z",
+        "updated_at": "2025-06-04T10:52:00.000000Z",
+        "oauth_provider_type": "google",
+        "oauth_provider_alias": "google"
+      }
+    ],
     "https://authgear.com/claims/user/authenticators": [
       {
         "created_at": "2025-06-04T10:50:00.00000Z",
@@ -69,6 +85,14 @@ The following section explains each standard attribute and examples of some cust
 * `given_name`: givenname of the current user.
 * `gender`: holds the value set for the current users' gender (male, female, or some other string).
 * `sub`: sub is short for "subject" and it is a standard field in O. The value is the user's unique ID generated by Authgear. You can use this user ID to generate a [user node ID](../../../reference/apis/admin-api/using-global-node-ids.md#id-1.-generate-id-for-user-node-type) which you can then use in **Admin API** to query a user or perform mutations.
+* `https://authgear.com/claims/user/identities`: this field contains an array of [identities](../../../concepts/user-identity-and-authenticator.md#identity) linked to the user. Each element always includes:
+  * `type`: identity type — `login_id`, `oauth`, `passkey`, `biometric`, `anonymous`, `siwe`, or `ldap`
+  * `created_at`: the timestamp of when the identity was created
+  * `updated_at`: the timestamp of when the identity was last updated
+
+  Additional fields are present depending on `type`:
+  * For `login_id`: `login_id_key` (configured key name, e.g. `"email"`) and `login_id_type` (resolved type: `"email"`, `"phone"`, or `"username"`)
+  * For `oauth`: `oauth_provider_type` (e.g. `"google"`) and `oauth_provider_alias` (the configured alias)
 * `https://authgear.com/claims/user/authenticators` : this field contains an array of information of [authenticators](../../../concepts/user-identity-and-authenticator.md#authenticator) owned by the user.
   * `created_at`: the timestamp of when the authenticator was created
   * `updated_at`: the timestamp of when the authenticator was last updated