Third Party Access

API Access

If you're a NoiseAware partner wanting to enable integration with the NoiseAware APIs you'll have to setup the following.

Before integrations can begin you'll need a NoiseAware representative manually provision you as a valid NoiseAware Partner. This entails us creating a Partner record for your company that contains these important pieces of information(provided by you):

  • ClientID: an identifier that we'll pass in the payload of the call to your ConnectionURL(see below). This identifier, combined with the below ClientSecret, is used as a way to authenticate NoiseAware during the access code retrieval call(see the section below on overall flow).
  • ClientSecret: the secret associated with the above ClientID.
  • ConnectionURL: This is a restful endpoint that we'll call in the authorizePartner step below that generates an access token for the user. This access token is what you'll pass to us in exchange for a JWT which you can use in the "authorization" header for subsequent NoiseAware API calls.

Once the NoiseAware representative has provisioned you as a valid partner they'll provide you with your PartnerId. You'll then use this during your calls to the NoiseAware authorize endpoint.

Overall flow:

1085
  • A user in your platform wants to enable integration with NoiseAware, and they initiate a process on your UI to begin.
  • You'll direct the user to login.noiseaware.io/authorize?code=<oneTimeCode>&id=<partnerId>&redirect=<redirectUrl>.
    • codeTimeCode: This is a one time code that you'll generate for this user authorize transaction. We'll pass this back to you in our call to your ConnectionURL.
    • partnerId: This is the PartnerId that we returned to you after manually provision you as a valid NoiseAware Partner. This determines which connectionURL NoiseAware will call in the later step to generate an authorization code (named access code in NoiseAware docs).
    • redirectUrl: The URL to redirect the user to after they've authorized the integration.
  • If the user has an existing account they will login, otherwise they'll sign up for a new account.
  • Once the user has authenticated into NoiseAware, they're presented with a screen to authorize the integration. The user clicks Authorize.
  • NoiseAware backend then calls the connectionURL that you provided to us during the manual provisioning step in order to get an authorization code (named access code in NoiseAware docs). See the section below on ConnectionURL details for more information.
  • We'll then store the authorization code (named access code in NoiseAware docs) generated from your ConnectionURL endpoint. This authorization code can then be used to generate a JWT token(see section below on Generating a JWT via an Authorization Code) which you can use in the "authorization" header for subsequent NoiseAware API calls.
  • The user is the redirected back to the URL specified by the redirectUrl query parameter sent during the NoiseAware authorize call login.noiseaware.io/authorize. The authorization code (named access code in NoiseAware docs) is added as a query parameter.
  • The authorization token is your per organization secret that can be exchanged for a bearer token using the portal.apps.noiseaware.io/token endpoint. See Generating a JWT via an Authorization Code for more details.

Note: NoiseAware's Third Party API access flow mostly follows the OAuth 2 Authorization Code flow with Proof Key for Code Exchange(PKCE) with a few notable exceptions:

  • In the OAuth 2 spec they call the token returned by the final authorization code exchange an Access Token, but NoiseAware uses the similar term access code for the authorization code. This is noted where it's important.
  • The initial call to /authorize does not contain a scope or response type, and the clientID is named 'id'.
  • The generation of the authorization code(referred to as access code in NoiseAware documentation) is done by the partner's connectionURL endpoint. The one time code, which is a part of PKCE, is never transformed but rather just sent raw. The one time code is then instead confirmed by the partner during NoiseAware's call to the connectionURL when getting the authorization code(access code).

ConnectionURL details

This section details the requirements of the Partner implemented endpoint for generating an authorization code(access_code). The endpoint must be an HTTP POST endpoint with the following requirements for JSON request and response bodies.

Request: {client_id: "identifier", client_secret: "secret", code: "oneTimeCode"}

  • The client_id and client_secret fields are what you, the partner, presented to NoiseAware during the initial manual Partner provisioning. These function as a basic authentication mechanism between NoiseAware and you.
  • The code field is the one time code you added as a query parameter when calling the login.noiseaware.io/authorize endpoint, when your user wanted to integrate with NoiseAware. This functions as a secondary security mechanism to ensure that in unlikely event the client_id and client_secret are compromised the attacker still cannot generate access codes. Please make sure this code is the same one you generated when initiating the user's integration.

Response: {access_code: ""}

Generating a JWT via an Authorization code(AccessCode)

To generate an bearer token(JWT) using your newly generated access_code you need to call POST portal.apps.noiseaware.io/token with the following payload(descriptions below): {accessCode: "", clientID: ""}

  • accessCode: The OAuth 2 authorization code generated as a part of the partner integration authorization.
  • clientID: The clientId that you gave to NoiseAware during the manual Partner provisioning step.

Response: {expiresAt: "", refreshToken: "", userToken: ""}

  • expiresAt: DateTime at which the user(bearer) token expires. This date is in format RFC 3309
  • userToken: The bearer token which you can use in the "authorization" header for subsequent NoiseAware API calls. This token is valid for 15 mins.
  • refreshToken: The refresh token which can be used in exchange for another user(bearer) token. This token is valid for 15 days.

Note: For token refresh see refresh Authentication