Authentication

Ducky's API is available to authenticated users only. Authentication is done via Auth0. In this article, you'll learn how to get your credentials, exchange them for a bearer token and use that token to make an authenticated request to the API.

Overview

The API requires an access_token for every request (except /ping).

Step-by-step:

  1. Ask Ducky (send an email to api@ducky.eco) for a CLIENT_ID and a CLIENT_SECRET
  2. Negotiate an access_token with Auth0
    • curl --request POST --url https://ducky-prod.eu.auth0.com/oauth/token --header 'content-type: application/json' --data '{"client_id":"$CLIENT_ID","client_secret":"$CLIENT_SECRET","audience":"ducky-api-prod","grant_type":"client_credentials"}'
  3. Send authenticated requests to Ducky API
    • curl --request GET --url https://api.ducky.eco/v3/ping/protected --header 'authorization: Bearer example_access_token'

Keep reading to learn how to obtain an access_token and use it to perform requests.

Prerequisite

In order to use the API, you have to ask for a CLIENT_ID and a CLIENT_SECRET. To do so, please contact Ducky at api@ducky.eco.

Note: even without an `access_token`, you can browse the documentation and explore its possibilities by looking at the example outputs.

Getting an access token

Request

Authentication is provided by Auth0.

To negotiate an access_token, send a request based on this curl snippet (update it with your $CLIENT_ID and $CLIENT_SECRET):

curl --request POST \
  --url https://ducky-prod.eu.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{"client_id":"$CLIENT_ID","client_secret":"$CLIENT_SECRET","audience":"ducky-api-prod","grant_type":"client_credentials"}'

Response

The response contains an access_token and an expiration time. You should store both and use the access_token until its expiration date (how you store them depends on your software architecture; If you are using Lambda/Cloud functions, make sure to share the token across instances). After expiration, repeat the process above to negotiate a new token.

{
  "access_token": "example_access_token",
  "token_type": "Bearer",
  "expires_in": 86400
}
Make sure to cache and reuse the `access_token` until its expiration date.
If we see unexpected high token exchanges, we will revoke your credentials and contact you directly.

Usage

Now that you have an access_token, you can start using the Ducky API. Send the access_token with each request, in the Authorization header. Make sure to prefix it with the token_type which is always Bearer.

Example

To make sure you're ready to use the API, you can use the /ping/protected endpoint. It validates your access_token and checks if the API is ready to accept connections.

curl --request GET \
  --url https://api.ducky.eco/v3/ping/protected \
   --header 'authorization: Bearer example_access_token'