Getting Started

The Propeller API is designed to allow 3rd parties access to a customer's Propeller data on their behalf.

Authentication and authorization

Authentication with Access Token

Generate your Access Token by navigating to Settings then Public API after logging into Propeller. Your access token is automatically generated and can be copied and used as the Bearer token for the the API.

If you need to revoke your Access Token for any reason the refresh button on the Propeller API settings page invalidates the old token and generates a new one.

Please note that the Access Tokens are user-scoped and persist across sites and portals.

Use Bearer <access_token> in the Authorization header with the access_token you received from the Setting page above to access your data.

curl --request GET \
 --url https://api.propelleraero.com/v1/organizations \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <access_token>'

You can also use this access token to explore the docs on this site. Simply hit "Try It" and provide "Bearer <access_token>" for the authorization header, as well as any parameters that are required.

Authentication with OpenID Connect

To allow secure 3rd party access to a customer's data with their permission, we have implemented part of the OpenID Connect 1.0 standard. We've chosen this method of authentication and authorization as it is considered best practice and avoids you having to handle any customer credentials directly.

As a relying party there are lots of different libraries to help with implementing your side of the specification. We recommend picking something from the certified list of OpenID Connect libraries for Relying Parties

To integrate with us, follow the steps below:

1. Download or link to our discovery document. Linking directly to the discovery document is recommended and most libraries will have an option for this. The discovery document sets out the various parts of the OpenID specification we have implemented, as well as the URI's of important endpoints.

2. Decide on your required callback endpoints (a library will come in handy when it comes time to implement these):

   • redirect_uris (should be a single endpoint or a list of endpoints, e.g. https://www.yourdomain.com/auth/callback)
   • post_logout_redirect_uris (should be a single endpoint or a list of endpoints, e.g. https://www.yourdomain.com/auth/logout/callback)

3. Decide on the scopes you require from the following:

   • openid - required scope
   • read:all - gives API access to site and measurement data
   • profile - returns the customers first and last name in the ID token/endpoint
   • email - returns the customers email address they log into Propeller with in the ID token/endpoint
   • offline_access - required to receive a refresh_token (recommended)

4. Decide on your client_name, this will be displayed on the OAuth consent screens and should be something the customer is familiar with, and will recognise as your unique organisation. Using the same name as your website or primary brand name is ideal. This can easily be changed later.

5. Pass these details from steps 2,3,4 to your contact at Propeller. We will then add you to our list of Relying Parties and generate your client_id and client_secret which we will send to you via a secure channel.

6. Implement your callbacks from step 2 as a relying party. Use the client_id and client_secret that you received, as well as the discovery document from step 1 with your chosen OpenID Connect library. Use the authorization_code grant type and remember to pass prompt=consent in the authentication request if you are requesting the offline_access scope.

7. Test the authentication/authorization flow.

   • You will be directed to the Propeller portal to log into your propeller account, if you are already logged in this step may be skipped.
   • You will be shown an authorization page, which details the scopes that are requested as well as the requester name (your client_name from step 4)
   • If the authorization is granted you will receive a set of tokens including the access_token, refresh_token and id_token.

8. Implement a way to save these tokens on your backend. You can use the refresh_token to request new access_tokens once the current ones expire.

9. Use the API: Use Bearer <access_token> in the Authorization header with the access_token you received from the OpenID Connect flow to access a customer’s data on their behalf, for example:

curl --request GET \
 --url https://api.propelleraero.com/v1/organizations \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <access_token>'

You can also use this access token to explore the docs on this site. Simply hit "Try It" and provide "Bearer <access_token>" for the authorization header, as well as any parameters that are required.