Using Identity URLs
The Identity URL is returned in the id scope parameter. For example, https://login.salesforce.com/id/00Dx0000000BV7z/005x00000012Q9P
.
The identity URL is also a RESTful API to query for additional information about users, such as their username, email address, and org ID. It also returns endpoints that the client can talk to, such as photos for profiles and accessible API endpoints.
The format of the URL is https://login.salesforce.com/id/_orgID_/_userID_
, where orgId is the ID of the Salesforce org that the user belongs to and userID is the Salesforce user ID.
You can use the following parameters with the access token and identity URL. You can use the access token in an authorization request header or a request with the oauth_token
parameter.
Parameter | Description |
---|---|
accesstoken | OAuth token that a connected app uses to request access to a protected resource on behalf of the client application. Additional permissions in the form of scopes can accompany the access token. |
format | Optional. Specify the format of the returned output. Values are:
The client can also specify the returned format in an accept-request header using one of the following formats.
The request header also supports the following.
The |
version | Optional. Specify a SOAP API version number or the literal string latest . If this value isn’t specified, the returned API URLs contain the literal value {version} in place of the version number. If the value is specified as latest , the most recent API version is used. |
PrettyPrint | Optional. Accepted only in a header and not as a URL parameter. Specify this parameter to optimize the returned XML or JSON output for readability rather than size. For example, use the following in a header: X-PrettyPrint:1 . |
callback | Optional. Specify a valid JavaScript function name. You can use this parameter when the specified format is JSON. The output is wrapped in this function name (JSONP). For example, if a request to returns {"function":"name"} , a request to returns baz({"function":"name"}); .Note: JSONP is no longer returned for Identity Service requests due to strict MIME typing. Your requests must add 'format=jsonp' with the callback parameter so that the Identity Service returns JavaScript. When the Identity Service detects the JSONP format, it returns the required JavaScript type ('application/javascript' ). |
With a successful request, the identity URL response returns information about the queried user and org.
The following identity URL response is in XML format.
And this response is in JSON format.
This table describes the returned parameters.
Parameter | Description |
---|---|
id | Identity URL, which is the same URL that was queried. |
asserted*user | Boolean value indicating whether the specified access token was issued for this identity. |
user_id | User ID of the queried user. |
username | Username of the queried user. |
organization_id | ID of the queried user’s Salesforce org. |
nick_name | Experience Cloud nickname of the queried user. |
display_name | Display name (full name) of the queried user. |
email | Email address of the queried user. |
email_verified | Indicates whether the queried user’s email was verified by clicking a link in the “Welcome to Salesforce” email. The email_verified value is set to
For example, a Salesforce admin creates the user Roberta Smith. Roberta receives a “Welcome to Salesforce” email message with a link to verify her account. After she clicks the link, the email_verified value is set to |
first_name | First name of the queried user. |
last_name | Last name of the queried user. |
timezone | Time zone specified in the queried user’s settings |
photos | Map of URLs to the queried user’s profile pictures, specified as picture or thumbnail .Note: Accessing these URLs requires passing an access token. See access token. |
addr_street | Street specified in the address of the queried user’s settings. |
addr_city | City specified in the address of the queried user’s settings. |
addr_state | State specified in the address of the queried user’s settings. |
addr_country | Country specified in the address of the queried user’s settings. |
addr_zip | Zip or postal code specified in the address of the queried user’s settings. |
mobile_phone | Mobile phone number specified in the queried user’s settings. |
mobile_phone_verified | Queried user confirmed that the mobile phone number is valid, |
status | Queried user’s current Chatter status.
|
urls | Map containing various API endpoints that can be used with the queried user Note: Accessing the REST endpoints requires passing an access token. See access token.
|
active | Boolean specifying whether the queried user is active. |
user_type | Type of the queried user. |
language | Language of the queried user. |
locale | Locale of the queried user. |
utcOffset | Offset from UTC of the queried user’s time zone, in milliseconds. |
last_modified_date | xsd datetime format of the last modification of the user, for example, 2010-06-28T20:54:09.000Z. |
is_app_installed | Value is true when the connected app is installed in the user’s org, and the user’s access token was created using an OAuth flow. If the connected app isn’t installed, the response doesn’t contain this value. When parsing the response, check for the existence and value of this property. |
mobile_policy | Specific values for managing a mobile connected app. These values are available only when the connected app is installed in the current user’s org, the app has a defined session timeout value, and the mobile PIN has a length value defined.
|
push_service_type | Set to apple if the connected app is registered with Apple Push Notification Service (APNS) for iOS push notifications. Set to androidGcm if it’s registered with Google Cloud Messaging (GCM) for Android push notifications. The response value type is an array. |
custom_permissions | When a request includes the custom_permissions scope parameter, the response includes a map containing custom permissions in the org associated with the connected app. If the connected app isn’t installed in the org or has no associated custom permissions, the response doesn’t contain a custom_permissions map.
|
Here’s an example request that includes the custom_permissions
scope parameter.
Here’s the JSON block in the identity URL response.