Authentication

OAuth2

The Noonlight API uses OAuth2 over SSL for authentication and authorization. You may find this straightforward if you've worked with OAuth2 before.

Access tokens

To use the Noonlight API, your app must send an OAuth2 access token in an Authorization header with each request. Currently, there is only one way of retrieving access tokens.

If you are requesting access to a Noonlight user's account in order to make requests on their behalf, you will go through a "3-legged" flow.

3-Legged flow for accessing user-specific endpoints

To create alarms, the user must grant you access. Users who don't have a Noonlight account will be prompted to create a new account if they are directed through the following flow.

Step 1: Obtaining access to the user's Noonlight account

First, direct the user to the following URL (hosted by Noonlight) with query parameters set appropriately for your application. The user will see information about your application, along with the list of permissions your application is requesting. The user can indicate whether Noonlight should grant access to your application or not.

🚧

Sandbox Environment

For testing, use https://account-sandbox.noonlight.com/authorize for the authorization URL.

# This request should originate from the logged-in user
GET https://account.noonlight.com/authorize?
	client_id=<client_id>&
	scope=<list_of_scopes>&
	state=<state_string>&
	response_type=code&
	redirect_uri=<redirect_uri>

Step 2: Handling the redirect

If the Noonlight user grants your application access to the requested permissions, Noonlight will issue a 302 redirect to the Redirect URI you've set up with Noonlight, along with an authorization code as a URL parameter. The authorization code should be used in the next step. It is a one-time use code and it will appear on your server like this:

GET 'https://your-redirect-uri/?code=<authorization_code>'

If you need help debugging the response to your server, consider configuring the Redirect URI as http://localhost or using a RequestBin.

Step 3: Retrieving an access token

Your server should retrieve a one-time-use authorization_code and pass it to Noonlight in order to retrieve an access token. The access token will enable you to make requests on behalf of the Noonlight user. Remember to include your application's client_id and client_secret in the POST body, as demonstrated below.

🚧

Sandbox Environment

For testing, use https://api-sandbox.noonlight.com/platform/oauth2/token for the token URL.

# This request comes from your server
curl -X POST -H "Content-Type: application/json" \
     -d '{"grant_type": "authorization_code", "code": <authorization_code>, "client_id": <client_id>, "client_secret": <client_secret>, "redirect_uri": <redirect_uri>}' \
     'https://api.noonlight.com/platform/oauth2/token'

POST /platform/oauth2/token HTTP/1.1
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": <authorization_code>,
  "client_id": <client_id>,
  "client_secret": <client_secret>,
  "redirect_uri": <redirect_uri>
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": <access_token>,
  "refresh_token": <refresh_token>,
  "token_type": "bearer",
  "expires_in": 36000
}

Step 4: Use the access token

API requests which require access tokens can now use the access_token returned from Step 3. When making requests you'll provide this access_token in the Authorization header, like in the example below:

curl -X POST \
  -H "Authorization: Bearer <Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "services": {
      "police": false,
      "fire": false,
      "medical": true
    },
    "location.coordinates": {
      "lat": 34.32334,
      "lng": -117.3343,
      "accuracy": 5
    }
}' \
https://api.noonlight.com/platform/v1/alarms

The access token expires after 10 hours, so you will need to refresh the tokens thereafter.

Step 5: Refreshing the access token

When the user's access token has expired, you may obtain a new access token by passing the refresh_token returned above. As with all POSTs in the 3-legged flow, remember to include your application's client_id and client_secret in the POST body.

🚧

Sandbox Environment

For testing, use https://api-sandbox.noonlight.com/platform/oauth2/token for the token URL.

curl -X POST -H "Content-Type: application/json" \
     -d '{"grant_type": "refresh_token", "client_id": <client_id>, "client_secret": <client_secret>, "refresh_token": <refresh_token>}' \
     'https://api.noonlight.com/platform/oauth2/token'

POST /platform/oauth2/token HTTP/1.1
Host: api.noonlight.com
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "client_id": <client_id>,
  "client_secret": <client_secret>,
  "refresh_token": <refresh_token>
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "refresh_token": <refresh_token>,
  "access_token": <access_token>,
  "token_type": "bearer",
  "expires_in": 36000
}