Factbird supports OAuth2 API Keys using the Client Credentials grant type.

OAuth2 API keys are perfect to use when you need secure machine-to-machine communication between your application from/to Factbird’s API.

One of the main benefits of using OAuth2 API keys is that the access tokens used to authenticate with the Factbird API are short-lived (typically 1 hour). This is great for security as this implements the security best-practice of rotation API keys.

If any questions arise while reading this page, please feel free to write [email protected]

Setting up OAuth2 clients via GraphQL mutations

There is not yet any UI on the Factbird application to create OAuth2 clients. Until that is developed, OAuth2 clients can be created through GraphQL mutations.

  1. Call the createAppClient mutation (docs) providing
    1. name - Desired name of the app client
    2. groupIds - Groups that the app client should be part of. At least one group is required.
  2. The createAppClient will respond with the following fields
    1. clientSecret - Secret of the client. This is not retrievable at a later time, so the caller must save this in a secure location.
    2. appClient - information about the created app client. Inside this is:
      1. id - Id of the created app client.

Generate short-lived access tokens

In the previous step, we created an OAuth2 app client, and in the process got a clientSecret and id of the app client.

These fields can not be used directly in Factbird API calls. Instead, one has to generate short-lived access tokens using the clientSecretand id. The access tokens are by default valid for 1 hour

  1. Make a POST request to https://auth.cloud.factbird.com/oauth2/token with the following headers set

    1. Authorization: Basic <authorizationToken> where <authorizationToken> is the result of base64 encoding clientSecret and id separated with :. Evaluated ahead of time like this: base64(id:clientSecret)
    2. Content-Type: application/x-www-form-urlencoded

    And with the following body grant_type=client_credentials&scope=factbird/api

  2. As a response, you will get an access token.

Making API calls with an OAuth2 access tokens

When making API requests to https://api.cloud.factbird.com, set the following headers