Skip to main content

Scopes and claims

Detailed developer guidance about the OpenID Connect scopes and claims that are supported by CIS2 Authentication.

Page contents

Overview

As per the Open ID Connect (OIDC) standard, when you make an authentication request to our authorisation endpoint, you need to specify the 'scopes' you want to have access to.

You must specify the oidc scope - this is always required for OIDC.

Any other scopes you specify determine what information, or 'claims', we return when you subsequently make a user info request to our user info endpoint.

For example, if you specify the profile scope, we will return the name, family_name, given_name and uid claims.

To specify the scopes you want, include them as a space-delimited list in the scope parameter of the authentication request, for example:

Example authentication request with scopes

HTTP/1.1 302 Found
  Location: https://am.nhsdev.auth-ptl.cis2.spineservices.nhs.uk:443/openam/oauth2/realms/root/realms/oidc/authorize?
    response_type=code
    &scope=openid%20profile%20nationalrbacaccess
    &client_id=999999999999.apps.national
    &state=af0ifjsldkj
    &redirect_uri=https%3A%2F%2Fwww.nationalsupplier.nhs.net%2Fcallback

Scopes

We support the following scopes:

Scope Type Description
oidc OIDC standard The only mandatory scope - you must include this scope.
profile OIDC standard Basic user profile information - name and ID.
email OIDC standard Information about the user's email address.
nhsperson Custom Detailed user profile information.
associatedorgs Custom Information about organisations the user has a role with.
nationalrbacaccess Custom Information about the user's national RBAC roles.
professionalmemberships Custom Information about the user's professional memberships.
organisationalmemberships Custom Information about the user's professional memberships in the context of a specific organisation. 
selectedrole Custom Triggers a role selection after an authentication - see Role selection.
changedrole Custom Triggers a change of role - see Role selection.

Claims

This section describes the claims that are returned from our user info endpoint. They are grouped by the scopes to which they relate. To receive the claims, you must have requested the related scope in your authentication request.

Most of the claims are derived from data held in the Spine Directory Service (SDS) and you can find additional useful information section 5.5 of the External Interface Specification.

Any claims contained in the user info response other than those listed below must be ignored.

oidc

This is a standard OIDC scope and you must include it. It causes a user info request to return the following claims:

Claim Description
sub A 12-digit identifier uniquely identifying the user within CIS, such as 999999999999. Sometimes called the UUID.

profile

This is a standard OIDC scope that provides basic user profile information. It causes a user info request to return the following claims:

Claim Description
name The user's full name using the format 'surname first name title', for example 'Smith Jane Ms'. Entries created in SDS prior to 2015 may use other formats. 
family_name The user's surname.
given_name The user's first name.
uid A 12-digit identifier uniquely identifying the user within CIS, such as 999999999999. Sometimes called the UUID, this is the same value as used in the sub claim.

email

This is a standard OIDC scope that provides the user's email address. It causes a user info request to return the following claims:

Claim Description
email The user's email address. This value may have been entered by the user or by the Registration Authority who created their identity. It is not verified and you should not assume that the user is in control of it. It is also not guaranteed to be present or up to date.

nhsperson

This is a custom scope that provides detailed user profile information. It causes a user info request to return the following claims:

Claim Description
nhsid_useruid A 12-digit identifier uniquely identifying the user within CIS2, for example 999999999999. Sometimes called the UUID, this is the same value as used in the sub and uid claims.
name The user's full name using the format 'surname first name title', for example 'Smith Jane Ms'. Entries created in SDS prior to 2015 may use other formats.
family_name The user's surname.
given_name The user's first name.
title The user's title, for example Mr.
idassurancelevel The level of assurance performed on the user's identity. This is a string value which can take one of the following values: 0, 1, 2 or 3. These values correspond to Identity Assurance Levels as defined in the NIST Digital Identity Guidelines for Enrollment and Identity Proofing Requirements. An assurance level of IAL3 gives a very high level of assurance of the user's identity including checks such as physical presence for identity proofing and verification of identifying attributes by a trained and authorised individual. You should validate that this claim has a value appropriate for your use case. For access to national clinical systems the idassurancelevel must be 3. This value is also present in the ID token as the id_assurance_level claim. For details, see Token request.
initials The user's initials - comes from the initials field within SDS.
middle_names The user's middle name(s) - comes from the nhsMiddleNames field within SDS.
display_name The user's display name - comes from the displayName field within SDS. This is often used to specify the user's preferred display name.

associatedorgs

This is a custom scope that provides information about organisations the user has a role with. It causes a user info request to return the following claims:

Claim Description
nhsid_user_orgs An array of the organisations at which the user has an assigned RBAC role. It contains an org_code and org_name for each organisation.
    org_code The organisation's code as defined by the Organisation Data Service.
    org_name The organisation's name as defined by the Organisation Data Service.

Example

{
  "nhsid_user_orgs":[
    {
      "org_code":"5JY",
      "org_name":"ROCHDALE PCT"
    },
    {
      "org_code":"Q14",
      "org_name":"GREATER MANCHESTER STRATEGIC HA"
    }
  ],
  "sub":"150254705103"
}

nationalrbacaccess

This is a custom scope that provides information about the user's national RBAC roles. It causes a user info request to return the following claims:

Claim Description
nhsid_useruid A 12-digit identifier uniquely identifying the user within CIS, for example 999999999999. Sometimes called the UUID, this is the same value as used in the sub and uid claims and corresponds to the uid of the nhsPerson object within SDS.
name The user's full name using the format 'surname first name' title, for example 'Smith Jane Ms'. Entries created in SDS prior to 2015 may use other formats.
nhsid_nrbac_roles An array of each of the user's roles. Each entry contains as a minimum: org_code, person_orgid, person_roleid, role_code and role_name. It may also contain arrays of activities, activity_codes, aow, aow_codes, workgroups and workgroup_codes that have been assigned to the user's role.
    org_code The organisation's code as defined by the Organisation Data Service.
    person_orgid A 12-digit identifier that uniquely identifies the user's association with the organisation. This corresponds to the uniqueidentifier of the nhsOrgPerson object within SDS.
    person_roleid A 12-digit identifier that uniquely identifies the user's role at the organisation. This corresponds to the uniqueidentifier of the nhsOrgPersonRole object within SDS. This is commonly referred to as the 'role profile code' and is used by national systems to audit what role a user was performing when they execute an action.
    role_code A colon-separated string of codes comprising a primary, secondary and tertiary job role code, for example S0080:G0440:R6050. Job role codes are typically referred to by their tertiary code which is a unique value, for example R6050.
    role_name A colon-separated string of names comprising a primary, secondary and tertiary job role name, for example "Admin & Clerical":"Admin":"Clinical Coder".  Job role names are typically referred to by their tertiary name, for example "Clinical Coder". The name parts are enclosed in "s as they may include special characters.
    activity_codes An array of activity codes assigned to the user's job role, for example B0021. Only activity codes explicitly granted to the job role are listed - the full set of activities that the user can perform must be determined by reference to the National RBAC database.
    activities An array of activity names assigned to the user's job role, for example Perform Discharge Administration. The order of entries in this array is not guaranteed to be the same as that for the associated codes.
    aow_codes An array of area of work codes assigned to the user's job role. Each code comprises a colon-separated string of a primary, secondary and tertiary area of work codes, for example P0010:Q0190:T0450. Area of work codes are typically referred to by their tertiary code which is a unique value, for example T0450. Area of work codes in conjunction with role code can be used to determine the full set of activities that the user can perform by reference to the National RBAC database.
    aow

An array of area of work names assigned to the user's job role. Each name comprises a colon-separated string of a primary, secondary and tertiary area of work names, for example "Medicine":"Gastroenterology":"Hepatology". Area of work names are typically referred to by their tertiary name, for example "Hepatology". The name parts are enclosed in "s as they may include special characters. The order of entries in this array is not guaranteed to be the same as that for the associated codes.
    workgroups_codes An array of codes identifying the work groups of which the user's job role is a member, for example 150255301108.
    workgroups An array of names of the work groups of which the user's job role is a member, for example Clinical Workgroup.

Example

{
  "nhsid_useruid":"150254705103",
  "name":"Grace Richard Mr",
  "nhsid_nrbac_roles":[
    {
      "org_code":"5JY",
      "person_orgid":"150255293108",
      "person_roleid":"150255303100",
      "role_code":"S0010:G0020:R0050",
      "role_name":"\"M&D\":\"Medical - M&D\":\"Consultant\"",
      "activity_codes":[
        "B0021",
        "B0022",
        "B0019"
      ],
      "activities":[
        "Perform Discharge Administration",
        "Print Discharge Summary",
        "View Discharge Summary"
      ],
      "aow_codes":[
        "P0010:Q0190:T0450",
        "P0010:Q0010:T0010"
      ],
      "aow":[
        "\"Medicine\":\"Gastroenterology\":\"Hepatology\"",
        "\"Medicine\":\"General Medicine\":\"Acute Medicine\""
      ],
      "workgroups_codes":[
        "150255301108",
        "150255302109"
      ],
      "workgroups":[
        "Clinical Workgroup",
        "Clinical Sub-Workgroup"
      ]
    }
  ],
  "sub":"150254705103"
}

The following example shows a user with two roles in different organisations. Note that if an attribute is not populated in SDS then no value is provided.

Example of user with two roles in different organisations

{
  "nhsid_useruid":"150254705103",
  "name":"Grace Richard Mr",
  "nhsid_nrbac_roles":[
    {
      "org_code":"Q14",
      "person_orgid":"150255297102",
      "person_roleid":"150255298103",
      "role_code":"S0080:G0440:R6050",
      "role_name":"\"Admin & Clerical\":\"Admin\":\"Clinical Coder\""
    },
    {
      "org_code":"5JY",
      "person_orgid":"150255293108",
      "person_roleid":"150255294109",
      "role_code":"S0010:G0020:R0100",
      "role_name":"\"M&D\":\"Medical - M&D\":\"Clinical Assistant\""
    }
  ],
  "sub":"150254705103"
}

professionalmemberships

This is a custom scope that provides information about the user's membership of professional bodies. It causes a user info request to return the following claims:

Claim Description
gmc_id

The user’s General Medical Council (GMC) number. A 7-digit numeric code, for example 0010856.
gdp_id The user’s General Dental Practitioner (GDP) number.  A letter 'D' followed by a 7-digit numeric code, for example D2015293.
gdc_id The user’s General Dental Council (GDC) number. A 5-digit numeric code, for example 79005.
rcn_id The user’s Royal College of Nursing (RCN) number.  A 7-digit numeric code, for example 1234567.
gmp_id The user’s Doctor’s Index Number formerly known as the General Medical Practitioner (GMP) code. A 6-digit numeric code, for example 041649.
nmc_id The user’s Nursing and Midwifery Council (NMC) number.  An 8-character code, for example 12A1234A.
consultant_id The user’s Consultant Code. A letter 'C' followed by the GMC code, for example C0010856.
gphc_id The user’s General Pharmacy Council (GPhC) number.  An 8-digit code consisting of an alpha and seven alpha/numeric fields, for example A123456A.
ocspr_code The user's OCS Practitioner Code - from the nhsOCSPRCode within SDS. An 8-character code consisting of a 'G' followed by 7 digits, for example G3468184.

You should not rely on the values of the claims as these are not actively managed by Care Identity Service.

organisationalmemberships

This is a custom scope that provides information about the user's membership of professional bodies in the context of the organisations for which they work. It causes a user info request to return the following claims:

Claim Description
nhsid_org_memberships An array of the organisations for which the user has professional memberships. It contains an org_code, org_name and gnc value for each organisation.
org_code The code of the organisation at which the user has the role as defined by the Organisation Data Service.
org_name The name of the organisation at which the user has the role as defined by the Organisation Data Service.
person_orgid A 12-digit identifier that uniquely identifies the user's association with the organisation. This corresponds to the uniqueidentifier of the nhsOrgPerson object within SDS.
gnc The user’s General National Code provided by the NHS Prescription Service to track prescribing activity. A code represents a prescribing cost code and is only unique in conjunction with a organisation association. A letter 'G' followed by a 7-digit numeric code, for example G0010856.

Example

{
  "nhsid_org_memberships":[
    {
      "org_code":"5JY",
      "org_name":"ROCHDALE PCT",
      "person_orgid":"150255293108",
      "gnc":"G0010856"
    }
  ],
  "sub":"150254705103"
}

Last edited: 18 February 2026 9:26 am