Authentication

Authenticate your API requests.

Server-side authentication

Use long-lived API Keys to authenticate server-side backend applications.

Client-side authentication

Use short-lived JWT tokens to authenticate client-side frontend applications.

Get your API credentials

To get your API credentials, create an Application in the Propel Console with DATA_POOL_QUERY and METRIC_QUERY scopes so they can access your data.

If you are using the Management API, you need an Application with ADMIN scope.

For step-by-step instructions, see the Creating an Application guide.

Server-side authentication

Authenticate server-side applications using an Application ID and secret as HTTP Basic Authentication credentials.

Use the Application ID as username and secret as password in the HTTP Basic Authorization header:

curl

curl -X POST https://api.us-east-2.propeldata.com/graphql \
-u $APPLICATION_ID:$APPLICATION_SECRET \
-H "Content-Type: application/json" \
-d '{"query": "query SqlV1 { sqlV1(input: { query: \"SELECT 1;\" }) { columns { columnName } rows } }"}'

Client-side authentication

Authenticate client-side frontend applications using short-lived JWT tokens. This involves a two-step process:

1. Generate a JWT token

   Make a POST request to the Token API endpoint with your Application credentials from secure backend code.

   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=$APPLICATION_ID&client_secret=$APPLICATION_SECRET"
   

   Replace $APPLICATION_ID and $APPLICATION_SECRET with your Application’s clientId and secret.

   The response includes:

   {
     "access_token": "eyJra...",
     "expires_in": 3600,
     "token_type": "Bearer"
   }
   
2. Make an authenticated request

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

   curl

   curl -X POST https://api.us-east-2.propeldata.com/graphql \
   -H "Authorization: Bearer eyJra..." \
   -H "Content-Type: application/json" \
   -d '{"query": "query SqlV1 { sqlV1(input: { query: \"SELECT 1;\" }) { columns { columnName } rows } }"}'
   

Error handling

400 Bad request

The Token API will return a 400 Bad Request response if:

• The grant_type parameter is missing or invalid
• The client_id parameter is missing or invalid
• The client_secret parameter is missing or invalid

To resolve this:

1. Verify you’ve created a Propel Application in your Account
2. Confirm your Application secret is correct
3. Ensure you include grant_type=client_credentials in the request

401 Unauthorized

The API will return a 401 Unauthorized response when using an invalid access token. Common causes include:

• The token has expired
• The token was revoked
• The token is malformed

Your application should handle 401 errors by requesting a new access token.

403 Forbidden

The API will return a 403 Forbidden response when the access token lacks the required permissions to access a resource. This means:

• The token does not have the necessary scopes
• The token does not have the required policies

Check your Application’s permissions in the Propel Console.