Authentication Roles

26 Apr

The ability to create tokens to control better control access to and usage of a Nightscout site was introduced with Grilled Cheese (0.9).

With current authentication options, you can create certain limited-use roles to:

  • Allow a caregiver the ability to see the site data but not make CarePortal/treatment entries
  • Allow a caregiver the ability to see the site and make CarePortal/treatment entries
  • Allow a caregiver total access to see the site, make entries, and use admin tools
  • Turn off access to someone that previously had access by removing their token (only possible if the site default is “denied”; see below)

To Take Advantage of Roles, Turn Off Unauthorized Access to Your Site

In a default setup, anyone with your Nightscout URL can view your site. (Depending on whether or not the treatment_auth variable (now deprecated) is set, using CarePortal may or may not require authorization with the API_SECRET.)

The new authentication roles (and AUTH_DEFAULT_ROLES variable) allow you to further control and limit access.

If you want to ensure that ONLY someone with permission to view your site (e.g., a token) is able to view the data, you should configure the AUTH_DEFAULT_ROLES variable in Azure or Heroku. Set the value as: denied.

This creates a scenario in which a token will be required for all access.

Create Authentication Tokens for Users

To access the Authentication options, click the settings panel (three horizontal bars in the top right) in your website and select Admin Tools. The Authentication options are at the top of the Admin page. (Note: you must be logged in with your API SECRET to access these tools.)



  • admin: full access
  • careportal: can view the site and make CarePortal/treatment entries
  • readable: read-only access; no ability to make CarePortal/treatment entries. This user CAN see reports and profile information.
  • denied: no access (this role only works if the AUTH_DEFAULT_ROLES setting is also “denied.” You can’t have a site that is readable to everyone and create a “denied” token for a specific user.)
  • devicestatus-upload: used by devices

Note: There is currently no way to limit a user so that the user can not view the Reports section, if the user has access to the site. Time/date-based roles are not currently possible.

Note: devicestatus-upload is a workaround that should only be used with older uploader applications.

Create a Token

  • Click the “Add New Subject” button.
  • Fill in the name of the subject and the “role” you are giving this subject (from the list of roles shown).
  • Click save.
  • The token will be shown. Copy the token URL (right-click on it in the browser and select the option to copy the link address) and provide it to the user (e.g., paste it into an email). If the user enters the entire URL (with token), the token will be in effect. Note: if the user copies only your core URL into a browser, and your site is readable by default, the token will be bypassed. (Possible strategies to ensure the user puts the role-based URL into a browser include using a tinyurl or


  • You can edit a subject by clicking the edit icon, making changes, and saving.
  • You can delete a subject by clicking the “x” icon to remove the subject from the list.

Word of Caution

If you provide a user a URL with a token, the user will see the main URL for the site and could access the site through the URL (without the token).

Submit any bugs, feedback, or issues via GitHub.