Scopes

Introduction

Different pieces of information are stored across a number of online resources, and some actions may be applied to those resources. Users may post shifts, accept shift requests, or change a facility profile information.

Your applications will want to make use of the information that has already been created in an online resource. To do so, your application requests for authorization to access this information on a user's behalf. Scopes define the specific actions applications can be allowed to do on a user's behalf.

How it works

1. To acquire the necessary scopes to perform actions on Nursa API resources you need to request it during the Authentication process by providing the list of scopes in the scope parameter of your initial request.
2. Nursa Authorization Server will check if the list of scopes is valid.
3. Nursa Authorization Server may request the user to give consent to your application to use those scopes.
4. Users can agree with that or even deny all or some of the required scopes.
5. Nursa Authorization Server will create an Access Token with the list of the allowed scopes. This list can be found in the scope claim of the Access Token.
6. Nursa Authorization Server will return the Access Token to you.
7. Your application will use the Access Token to call Nursa API resources.
8. Nursa API resource may accept (HTTP 2**) the request if necessary scopes are present in the token or will deny (HTTP 403) the access if a required scope is missing.

Note: Different resources will require different scopes.

UserInfo Scopes

Scopes are also used to grant access to user profile information like email, avatar picture, and address. The claims described here will be included in the ID Token and on /userinfo endpoint. Nursa Authorization Server supports the following user scopes:

• openid: returns the sub claim, which uniquely identifies the user. In an ID Token, iss, aud, exp, iat, and at_hash claims will also be present.
• profile: returns claims that represent basic profile information, including name, nickname, and picture.
• email: returns the email claim, which contains the user's email address.
• phone: returns the phone_number claim, which contains the user's phone number.
• address: returns the address claim, which is an object with city and state properties containing the user's address information.
• role: returns the role claim, which indicates the user role in Nursa, it can be NURSE_USER or FACILITY_USER.

Refresh Token Scope

Sometimes you want to keep the user session alive for a long time, so you need to use a Refresh Token. To obtain a Refresh Token you need to request the offline_access scope during the Authentication process.

• offline_access: returns a refresh_token property from the Get Token endpoint.

Resource Scopes

To access the Nursa API resource your application may require some of the following scopes, depending on your application needs. The API documentation will define which scopes will be requested for each endpoint.

Scope Name	Scope Value	Scope Description
Post Shifts	marketplace:write	User allows your application to post and update shifts on their behalf.
View Posted Shifts	marketplace:read	User allows your application to read shifts on their behalf.
Manage Shift Policy	marketplace-policy:write	User allows your application to manage shift policy on their behalf.
View Shift Policy	marketplace-policy:read	User allows your application to read shift policy on their behalf.
Manage Shift Requests	shift-requests:write	User allows your application to manage shift requests on their behalf.
View Shift Requests	shift-requests:read	User allows your application to read shift requests on their behalf.
Manage Shift Reports	shift-reports:write	User allows your application to manage shift reports on their behalf.
View Shift Reports	shift-reports:read	User allows your application to read shift reports on their behalf.
Manage Facility Profile	facilities:write	User allows your application to manage the facility profile on their behalf.
View Facility Profile	facilities:read	User allows your application to read the facility profile on their behalf.
Manage Financial Information	finances:write	User allows your application to manage the facility's financial information on their behalf.
View Financial Information	finances:read	User allows your application to read the facility's financial information on their behalf.
Manage Communication Policy	communication-policy:write	User allows your application to manage the communication policy on their behalf.
View Communication Policy	communication-policy:read	User allows your application to read the communication policy on their behalf.
Manage Permissions	permissions:write	User allows your application to manage the user permissions under an organization on their behalf.
View Permissions	permissions:read	User allows your application to read the user permissions under an organization on their behalf.
Manage Integrations	integrations:write	User allows your application to manage the integration settings of the organization on their behalf.
Manage OIDC Applications	oidc-application:write	User allows your application to manage the Open ID Connect applications of the organization on their behalf.
View OIDC Applications	oidc-application:read	User allows your application to read the Open ID Connect applications of the organization on their behalf.