Using Identity URLs

The Identity URL is returned in the id scope parameter. For example,

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, 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.

accesstokenOAuth 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.
formatOptional. Specify the format of the returned output. Values are:
  • json

  • xml

The client can also specify the returned format in an accept-request header using one of the following formats.

  • Accept: application/json

  • Accept: application/xml

  • Accept: application/x-www-form-urlencoded

The request header also supports the following.

  • The / wildcard is accepted and returns JSON.

  • A list of values, which is checked left to right. For example: application/xml,application/json,application/html,/_ returns XML.

The format parameter takes precedence over the access request header.

versionOptional. 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.
PrettyPrintOptional. 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.
callbackOptional. 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 https://server/id/orgid/userid/ returns {"function":"name"}, a request to https://server/id/orgid/userid/?callback=baz 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.

idIdentity URL, which is the same URL that was queried.
asserted*userBoolean value indicating whether the specified access token was issued for this identity.
user_idUser ID of the queried user.
usernameUsername of the queried user.
organization_idID of the queried user’s Salesforce org.
nick_nameExperience Cloud nickname of the queried user.
display_nameDisplay name (full name) of the queried user.
emailEmail address of the queried user.
email_verifiedIndicates 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 true when users click a link in the email they receive after the following:

  • They change their email address

  • They change their password, or a Salesforce admin resets their password

  • They verify their identity when logging in from a new device or browser

  • A Salesforce admin creates them as a new user

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 true.

first_nameFirst name of the queried user.
last_nameLast name of the queried user.
timezoneTime zone specified in the queried user’s settings
photosMap 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_streetStreet specified in the address of the queried user’s settings.
addr_cityCity specified in the address of the queried user’s settings.
addr_stateState specified in the address of the queried user’s settings.
addr_countryCountry specified in the address of the queried user’s settings.
addr_zipZip or postal code specified in the address of the queried user’s settings.
mobile_phoneMobile phone number specified in the queried user’s settings.
mobile_phone_verifiedQueried user confirmed that the mobile phone number is valid,
statusQueried user’s current Chatter status.
  • created_datexsd datetime value of the creation date of the last post by the user, for example, 2010-05-08T05:17:51.000Z.

  • body—Body of the post.

urlsMap 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.
  • enterprise (SOAP)

  • metadata (SOAP)

  • partner (SOAP)

  • rest (REST)

  • sobjects (REST)

  • search (REST)

  • query (REST)

  • recent (REST)

  • profile

  • feeds (Chatter)

  • feed-items (Chatter)

  • groups (Chatter)

  • users (Chatter)

  • custom_domain

    Note: If the org doesn’t have a custom domain configured and propagated, this value is omitted.

activeBoolean specifying whether the queried user is active.
user_typeType of the queried user.
languageLanguage of the queried user.
localeLocale of the queried user.
utcOffsetOffset from UTC of the queried user’s time zone, in milliseconds.
last_modified_datexsd datetime format of the last modification of the user, for example, 2010-06-28T20:54:09.000Z.
is_app_installedValue 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_policySpecific 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.
  • screen_lock—Length of time to wait to lock the screen after inactivity.

  • pin_length—Length of the identification number required to gain access to the mobile app.

push_service_typeSet 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_permissionsWhen 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.