Types of Authentication

The Bluesonde API supports two main access paradigms: API Keys and OAuth.

API Keys

API keys enable you to access data from your own account in a programmatic way. To provision one, simply go to the Developer Settings page, click on ‘Create an API Key’, and fill out the form to suit your needs.

To create an API key, your account needs the Organization Admin role at minimum.

If you have difficulty accessing the above page, reach out to your organization administrator, or contact us.

Once created, you will be given a single opportunity to copy your key. Use this opportunity to persist your key in a secure fashion. This key enables anyone who has it access to your account information, and is thus a secret. It should not be shared, stored in plaintext, or distributed to other users or companies.

To use your API key, simply include it as a Bearer token in the Authorization header e.g. Authorization: Bearer sk_live_abcxyz…789 . Try it out in our interactive documentation!

OAuth2

Broadly speaking, OAuth enables Bluesonde users to consent to allowing third-party programmatic access to their data.

The Bluesonde API also supports OAuth2.0 with the authorization code grant type. OAuth2.0 enables you (as a third party) to access data from consenting user’s accounts. This authentication method is geared towards developers and application owners who want to access data from their customer’s accounts.

To use this method of authentication, you must first register your application as an OAuth Client on our site. Specifically, navigate to the Developer Settings Page, switch to the OAuth Applications tab, click on ‘Create an OAuth Application’, and follow the form to suit your needs.

When filling out the form, note the function of the following fields:

• Application Name

  • This is the name of your application. It will be shown to users during the consent process and should be recognizable.

• Redirect URIs

  • URIs in this list are pages on your application that are designed to receive the authentication code post-login flow.

• Scopes

  • These are the scopes your application requires. For example, if you require device data, you will need the devices:read scope selected.

  • Notably, in order to consent to your application’s access to their data, end users will need a role that has every scope listed here.

  • In order to access data without continually consenting users, add the offline_access scope.

Note that some fields (e.g. privacy policy URL) are optional, but greatly add to the ‘trust factor’ of your application for consenting users.

Once your client has been created, you will be prompted to store your client ID and secret. You will need this information to onboard and consent your users.

If your application cannot effectively secure the client secret, please select the PKCE option when creating your client. This will enable a ‘secret-less’ login flow.

With your client ID and secret in hand, you kick off the OAuth flow. Specifically, the following endpoints will be relevant:

• https://auth.bluesonde.io/oauth2/auth

  • This is the URL where you begin the authorization code exchange. We recommend using one of the many client libraries out there for navigating the exchange, but if you’re inclined to do this on your own include the information below as query parameters:

    • response_type=code

      • This indicates you want an authorization code returned

    • client_id=<your-client-id>

      • This is the ID of the application requesting access

    • redirect_uri=<your-redirect-uri>

      • This is the page you want your users redirected to after login. It should be one of the URLs you registered your application with.

    • scope=<space-delimited-string-of-requested-scopes>

      • This is the set of scopes your application is requested access to.

    • state=<a-random-value>

      • This is a random value designed to prevent CSRF.

• https://auth.bluesonde.io/oauth2/token

  • This is the URL where you can exchange the code you got as a result of the login flow for an access token. When hitting this endpoint manually, structure your request with the following information:

    • Query Parameters

      • grant_type=authorization_code

        • This indicates you are providing an authorization code.

      • code=<authorization-code>

        • This is the authorization code received from the results of the first step

      • redirect_uri=<your-redirect-uri>

        • This is the page you want your users redirected to after the code is exchanged.

    • Headers

      • Content Type application/x-www-form-urlencoded

      • Authorization Basic <your-client-id>:<your-client-secret>

  Once you’ve gone through the authorization flow, you will be able to use the token given to access your user’s data. It can be used as a Bearer token in the Authorization HTTP header.

Using your Credentials

Whether it’s an API Key or Access Token, using your credentials is easy. Simply place your credentials as a Bearer token in the Authorization HTTP header (e.g. Authorization Bearer <your-token-here> when making your request.

If you’re interested in getting data in an asynchronous way, check out the section on Webhooks. If you’d like to know more about the entities you’ll encounter using our API, check out the Data section.