API v1 Security

API Secret authentication

To make sure no one accesses your data or changes your security, the API has a simple hashed security key that you needs to match both the server and the client.

Before you can use the API you need to set API_SECRET in your server's Config Variables to a secure password of your choosing. The API converts the API_SECRET into a SHA1 hash at runtime.

To authenticate with the API your app needs to send the same API_SECRET password as a SHA1 Hash in the HTTP Headers as API-SECRET (note the underscore on the server, and dash in the HTTP Headers on your client app). You may test to confirm your API_SECRET is handshaking properly using a REST client to point to this endpoint on your Nightscout server.

/api/v1/experiments/test

Just make sure you use a dash instead of an underscore in the HTTP Header (API-SECRET), and you SHA1 Hash your password. If your password is sent as clear text to the API it will be rejected. You can hash your password for testing with the REST client at www.sha1-online.com. But please make the app that you are writing configurable so that your user may change the password at any time.

Token authentication

The V1 REST API also supports authentication by using the access tokens created in the Subjects - People, Devices, etc. section of the Admin Tools. To authenticate using a token, you have two options:

1. Send the token without hashing in the API-SECRET header, and
2. Request a JWT token by sending an access token as a REST GET to /api/v2/authorization/request/<token>, parse the token from the results, and then in subsequent requests using the Bearer authorisation method of sending Authorization: Bearer <JWT> in each REST API call. Note the JWT expires periodically and you need to re-request the JWT as it expires. The exp parameter in the call to fetch the token will contain the expiration timestamp for the token.

Closing unauthenticated API reads

Set the AUTH_DEFAULT_ROLES variable to denied to prevent unauthenticated reads.