Authentication

Propel authenticates GraphQL API requests using the OAuth2 Client Credentials Flow. This authentication mechanism provides the ability to grant granular scopes to different applications, grant frontend applications time-bound tokens, and easily revoke credentials from individual applications when needed.

This guide explains the mechanics of the OAuth2 Client Credential Flow and provides a step-by-step guide to authenticate with Propel's APIs.

• About the OAuth2 Client Credential Flow
• Step 1: Create an Application
• Step 2: Generate an Access Token
• Step 3: Make API Requests
• Error Handling
• Revoking API credentials

---

Requirements

• You have a Propel Account.

---

About the OAuth2 client credential flow

Propel uses OAuth2's Client Credentials Flow to issue access tokens on behalf of your applications. The following diagram illustrates the OAuth flow based on the actions of your application.

Key terminology

• Your application - The web or mobile application you are building.
• Propel Application - The Propel Application object that represents an OAuth2 Client.
• Access token - The credentials used to access protected resources. An access token is a string representing an authorization issued to your application.

%%{init: { "theme": "dark", "sequence": { "showSequenceNumbers": true } } }}%% sequenceDiagram Your Application->>+Token API: Request access token Token API->>-Your Application: Token API returns an access token Your Application->>+Propel API: Your application makes an API request using the access token Propel API->>-Your Application: Propel API returns the response

1. Your application requests an access token to the Token API using Propel's Application client identifier and client secret.
2. The Token API responds with an access token.
3. Your application then makes a request to the Propel API, including the access token in the Authorization header.
4. Propel API returns the response.

Step 1: Create an Application

Propel Applications give you scoped access to the Propel API and data resources. Consider every customer-facing application, such as your web or mobile app, being its own Propel Application. That way, you have scoped API credentials for each and can manage the credential lifecycle independently.

The first step is to create a Propel Application in the Console. Once you create it, you will have a client identifier and secret that you can use to generate access tokens.

1. Log in to the Propel Console.
2. Click on Applications.
3. Click on Create Application.
4. Enter a unique name and description.
5. Give your Application the scopes it needs.
6. Scroll to the OAuth2 Client Credentials section to see your clientId and secret.

caution

Do not share your secret value with anyone. Do not pass it in the URL or query string parameters when making API calls. Do not check it into your git repository.

tip

Store your clientId and secret in a secure service like AWS Secrets Manager or the Google Cloud Secret Manager.

Step 2: Generate an access token

To generate an access token, issue an HTTP POST request to the Token API endpoint with your client_id and client_secret values.

Token API Endpoint

https://auth.us-east-2.propeldata.com/oauth2/token

The Token API takes the following as body parameters:

Parameter	Description	Required
grant_type	The value of this field should always be client_credentials.	Yes
client_id	Your Propel Application's clientId value.	Yes
client_secret	Your Propel Application's secret value.	Yes
scope	Omit to use scopes set for the Application. Only use if you want to further restrict access.	No
tenant	The tenant ID for tenant-level access policies. More info.	No

caution

The Propel API returns clientId and secret in the Application object following the camel case convention we use throughput the API. However, note that the Token API takes snake case parameters client_id and client_secret that follow the OAuth 2.0 RFC specification.

Sample token request

HTTPS

POST /oauth2/token HTTP/1.1
Host: auth.us-east-2.propeldata.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

Curl

curl -X POST https://auth.us-east-2.propeldata.com/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Node

import fetch from 'node-fetch'

const response = await fetch(
  'https://auth.us-east-2.propeldata.com/oauth2/token',
  {
    method: 'post',
    body: 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
  }
)
const data = await response.json()

console.log(data.access_token)

Sample token response

A successful access token request returns a JSON object containing the following fields:

• access_token — The access token for your application. This token must be kept secure.
• expires_in — Seconds until token expiration. The access token has a one hour lifespan and should be used immediately. You may request a new token when your current one expires.
• token_type — The type of token returned. Useful to build the Authentication header.

JSON Response

{
    "access_token":"eyJra...",
    "expires_in":3600,
    "token_type":"Bearer"
}

Step 3: Make API requests

Once you've received an access token, your application makes API requests by including the Authorization header with your access token.

Sample GraphQL request

HTTPS

POST /graphql HTTP/1.1
Host: api.us-east-2.propeldata.com
Authorization: Bearer <ACCESS_TOKEN>

{getAllDataSources (first:10) { pageInfo edges }}

Curl

curl -X POST https://api.us-east-2.propeldata.com/graphql \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d "{getAllDataSources (first:10) { pageInfo edges }}"

Node

import fetch from 'node-fetch'

const response = await fetch('https://api.us-east-2.propeldata.com/graphql', {
  method: 'post',
  headers: { Authorization: 'Bearer <ACCESS_TOKEN>' },
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify('{getAllDataSources (first:10) { pageInfo edges }}')
})
const data = await response.json()

console.log(data.access_token)

Error handling

400 Bad request

A Token API request with invalid grant_type, client_id, or client_secret parameters will result in a 400 Bad Request response.

Make sure you've created the Propel Application in your Account, that the secret is correct, and that you've included the grant_type=client_credentials parameter and value.

401 Unauthorized

An API request using an invalid token will receive a 401 Unauthorized response. In this case, the token will need to be regenerated because it expired or was revoked.

These are not the only reasons for an invalid token. Make sure you code your applications to handle a 401 error properly.

403 Forbidden

If the access token does not have the required scopes or policies to access a particular Propel resource, it will receive a 403 Forbidden.

Revoking API credentials

You can revoke API credentials by deleting the Propel Application in the Console. Once you delete a Propel Application, its clientId and secret are no longer valid. Without a valid clientId and secret, your application cannot generate access tokens. Without access tokens, your application cannot access the Propel API.