Request

Response

    Custom Scopes

    The User Profile API uses custom OAuth scopes to provide fine-grained access control. These scopes replace broader scopes (such as data:read and data:write) and allow your application to request only the level of access it needs.

    When generating an access token, include the appropriate custom scopes for the operations your application performs. For general information on OAuth flows and token generation, see Authentication.

    Important: Custom scopes control field-level access. They do not allow two-legged OAuth tokens to be used from browser or web-property traffic on GraphQL Profile. Server-to-server two-legged OAuth and browser three-legged access token requirements are documented in Authentication Patterns.

    Tip — Quick Reference

    • Multiple scopes are allowed in a single token.
    • Mixed scopes (read and write) are allowed.
    • Multiple scopes must be space-separated (e.g. profapi:core-std-profile:read profapi:img-profile:read).
    • A write scope automatically grants the corresponding read scope.
    • Most requests only need profapi:core-std-profile:read.

    Available Custom Scopes

    Read Scopes

    ScopeDescription
    profapi:core-std-profile:read Read standard core user profile fields. Grants access to a subset of core profile fields (see core-std vs core-all below).
    profapi:core-all-profile:read Read all core user profile fields. Grants access to every field on the core user profile.
    profapi:img-profile:read Read profile image data. Required to access the profileImages field on a user profile.
    profapi:screening-status:read Read Export Control screening status (userProfile.complianceInfo.ecInfo). Commercial environments only.

    Write Scopes

    ScopeDescription
    profapi:core-std-profile:write Update standard core user profile fields. Allows mutations on the subset of core profile fields (see core-std vs core-all below).
    profapi:core-all-profile:write Update all core user profile fields. Allows mutations on every field of the core user profile.

    core-std vs core-all

    The core profile scopes come in two tiers. Use core-std if your application only needs the fields listed below. Use core-all if your application accesses any fields beyond this list.

    Fields Accessible with core-std-profile:read

    Field PathType
    userId String
    identifiers.eidmId String
    personalInfo.primaryEmail String
    personalInfo.language String
    personalInfo.countryCode String
    personalInfo.basicInfo.firstName String
    personalInfo.basicInfo.lastName String
    personalInfo.basicInfo.screenName String
    personalInfo.professionalInfo.jobTitle String
    personalInfo.professionalInfo.industry String

    Any field not listed above (for example, aboutMe, contactInfo, webLinks, ldapInfo) requires profapi:core-all-profile:read. Requesting an unlisted field with only core-std scope returns null for that field and a FIELD_ACCESS_RESTRICTED error.

    Fields Accessible with core-std-profile:write

    Input FieldType
    id String
    emailId String
    firstName String
    lastName String
    screenName String
    countryCode String
    language String
    professionalInfoInput.jobTitle String
    professionalInfoInput.industry String

    Including any input field not listed above in a mutation (for example, websiteUrl, contactInput) with only core-std scope causes the entire mutation to be rejected with a FIELD_ACCESS_RESTRICTED error. Use profapi:core-all-profile:write if your application updates fields beyond this list.

    Combining Multiple Scopes

    Your application can request multiple custom scopes in a single token. This is required when your query accesses data gated by different scopes.

    Example: To read core profile fields and profile images in a single query, your token must include both scopes:

    profapi:core-std-profile:read profapi:img-profile:read
    

    The query:

    query GetUserProfile($filter: UserProfileInput!) {
      userProfile(filter: $filter) {
        userId
        personalInfo {
          primaryEmail
          basicInfo {
            firstName
            lastName
          }
        }
        profileImages {
          isImagePresent
          userThumbnails {
            sizeX120
          }
        }
      }
    }
    
    Show More

    If either scope is missing, the fields gated by the missing scope return null with a FIELD_ACCESS_RESTRICTED error, while other fields succeed normally (partial response).

    Error Behavior

    When your token lacks a required scope, the API returns a FIELD_ACCESS_RESTRICTED error. Depending on the operation:

    • Queries: The restricted field returns null and an error entry appears in the errors array. Other fields in the same query succeed (partial response).
    • Mutation inputs: If a disallowed field is included in the mutation input, the entire mutation is rejected before any data is written.
    • Mutation responses: The mutation succeeds for allowed input fields, but restricted fields in the response return null with an error.

    For detailed error examples and handling guidance, see GraphQL Error Handling.

    REST API Scopes (OIDC UserInfo)

    The custom scopes described above also apply to the REST /userinfo endpoint. However, there is a key difference: the openid scope is mandatory for all REST UserInfo requests. Tokens without openid will receive a 403 Forbidden response.

    Important: Unlike the GraphQL API, the REST /userinfo endpoint requires the openid scope in every request. Ensure your token generation logic includes openid along with the appropriate scopes listed below.

    Available Scopes for /userinfo

    ScopeFields Returned
    openid (mandatory) sub
    email email, email_verified
    profapi:core-std-profile:read sub, name, given_name, family_name, email, language, country_code, job_title, industry, eidm_guid
    profapi:core-all-profile:read sub, name, given_name, family_name, preferred_username, email, email_verified, profile, locale, updated_at, is_twofa_enabled, country_code, address, phone_number, phone_number_verified, ldap_enabled, ldap_domain, job_title, industry, industry_code, about_me, language, company, created_date, last_login_date, eidm_guid, opt_in, social_userinfo_list, twofa_type, contact_mode, user_source_type, alternate_email
    profapi:img-profile:read picture, user_thumbnails

    Note: core-std vs core-all — If your application only needs sub, name, given_name, family_name, email, language, country_code, job_title, industry, and eidm_guid, use profapi:core-std-profile:read. If it needs any fields beyond that list, use profapi:core-all-profile:read instead.

    Examples

    Read standard profile fields:

    openid profapi:core-std-profile:read
    

    Returns: sub, name, given_name, family_name, email, language, country_code, job_title, industry, eidm_guid.

    Read standard profile fields + profile images:

    openid profapi:core-std-profile:read profapi:img-profile:read
    

    Returns the core-std fields plus picture and user_thumbnails.

    Read all core profile fields:

    openid profapi:core-all-profile:read
    

    Returns all core profile fields for which the user has data.

    Error Response

    If openid is missing from the token, the endpoint returns:

    {
      "error": "invalid_scope",
      "error_description": "openid scope is required for /userinfo"
    }
    

    For the full REST endpoint reference, see GET OIDC User Info.