Machine to Machine Authentication

If you are writing an application that will authenticate and fetch data from PRODA, M2M authentication allows you to easily automate the authentication process. To use it, please contact us to set it up in case you haven't yet. The rest of this assumes you have received both a client ID and a client secret from PRODA.

The first thing your app must do is to retrieve an access token. Only with that will your app be able to fetch data.

The request to retrieve an access token must be issued to Auth0. It is an HTTP request as such:

It is a POST request
The URL is https://proda.eu.auth0.com/oauth/token
The payload must be that of an HTML form with four input fields:
- audience=https://app.proda.ai/thirdparty/
- grant_type=client_credentials
- client_id=YOUR_CLIENT_ID
- client_secret=YOUR_CLIENT_SECRET

The last two form fields must be replaced with your client ID and secret. The cURL equivalent of this request is:

curl --request POST \
--url 'https://proda.eu.auth0.com/oauth/token' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'audience=https://app.proda.ai/thirdparty/&grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

That endpoint will return a JSON response with an access_token field. This JWT token must be passed through in an Authentication: Bearer xxx header in most HTTP calls to the API.

You should now be able to query PRODA's API's endpoints. Continue reading to learn about them and to experiment with the API in this page. Also, we strongly recommend you read the important notes regarding access tokens section before you develop your app.

Once authenticated, you can use the endpoint as described in our API reference

Important notes regarding access tokens

This section is very important and not abiding by some of these guidelines could even make the API suddenly stop working for you.

Be conservative in retrieving access tokens

Access tokens are limited in quantity, and obtaining access tokens too frequently will reach a maximum monthly quota. After that, you won't be able to retrieve new ones and won't be able to use the API until the next month.

Access tokens are valid for 24 hours, so your code should store and reuse the latest access token as much as possible.

Do not assume HTTP 401 responses mean the access token has expired

There are other causes for HTTP 401 responses, so retrieving new access tokens when you get one could put you into a loop that maxes out your monthly token quota.

We recommend checking the databases-list endpoint when you receive an HTTP 401 response. No longer belonging to a Company Database is a likely cause - other than expiring tokens - that will make PRODA's API return HTTP 401 responses. If even databases-list returns 401, then you should get a new access token.