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
| Scope | Description |
|---|---|
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
| Scope | Description |
|---|---|
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 Path | Type |
|---|---|
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 Field | Type |
|---|---|
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
}
}
}
}
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
nulland an error entry appears in theerrorsarray. 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
nullwith 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
| Scope | Fields 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.