To access DRIVR's GraphQL and REST APIs, all requests must be authenticated using a bearer token. This guide explains how to obtain and use bearer tokens for secure API access.

Prerequisites

Please note:

Domain Configuration: Authentication flows depend on the configurations made at the Domain level using DomainAuthenticationMethods and at the application level using ApplicationConsumers. If you're unfamiliar with these concepts, please refer to the previous chapters. OpenID Configuration:
All authentication endpoints and OpenID configuration details can be retrieved from:
https://{slug}.api.drivr.cloud/.well-known/openid-configuration
Replace {slug} with your domain's slug.

Supported Authentication Flows

DRIVR supports the following authentication flows. Depending on your setup, you can choose the one that best fits your needs.

1. Authorization Code Grant

The Authorization Code Grant is an OAuth 2.0 flow designed for server-side applications. It allows users to securely authorize applications to access their resources. This flow is ideal for applications that can securely store client secrets. Read more : https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.1

Setup

To use this flow, create an ApplicationConsumer with the grantType : AUTHORIZATION_CODE . Optionally, you can enable the REFRESH_TOKEN grant type to allow the issuance of refresh tokens.

Refer to the Application Consumer Guide for detailed steps on creating this ApplicationConsumer using DRIVR's GraphQL API.

How It Works

1. If your domain has multiple DomainAuthenticationMethods, users will be redirected to the DRIVR Login UI to select an authentication method.
2. If only one external method (e.g., Google or Azure AD) is configured, users will be redirected directly to the provider.
3. If the internal DEFAULT method or more than one external method is configured, the DRIVR Login UI will prompt users to log in with their DRIVR credentials or let them choose which provider they would like to use.

2. Resource Owner Password Credentials

This flow allows applications to directly exchange a user's credentials (username and password) for an access token. This flow is suitable for trusted applications. Read more: https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.3

Setup

To implement this flow, use DRIVR's GraphQL API to create an ApplicationConsumer with the grantType: PASSWORD. Follow the instructions provided in the Application Consumer Guide to complete the setup.

Example Request for REST API :

Note: Replace {slug} with your domain's slug.

POST /authenticate/token HTTP/1.1
Host: https://{slug}.api.drivr.cloud
Content-type: application/x-www-form-urlencoded

grant_type=password
&username=exampleuser
&password=1234luggage
&client_id=my-app.localhost

How It Works

1. The client application collects the user's credentials (username and password).
2. DRIVR validates the provided credentials and checks if the user exists in the system.
3. If the credentials are valid, DRIVR issues an access token (and optionally a refresh token, if configured).
4. The client application uses the access token to authenticate subsequent API requests.

Note: This flow should only be used by trusted applications, as it requires handling user credentials directly.

3. OpenID Delegation

This method allows users to authenticate with DRIVR using OpenID tokens from trusted third-party providers (e.g., Auth0, Google, Azure AD, and others).

Setup

To use this method, create a new DomainAuthenticationMethod with the OPEN_ID_BEARER_DELEGATION type.

Refer to the OpenID Provider Integration Guide for detailed steps on configuring this method using DRIVR's GraphQL API.

How It Works

1. Users log into a trusted third-party service and obtain an OpenID token.
2. The token is passed to DRIVR as a Bearer Token.
3. DRIVR validates the token's signature and checks its issuer and audience.
4. If the user does not exist in DRIVR, it is automatically created.

Examples

Python Example:

import requests

ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN_HERE'
DOMAIN_SLUG = 'slug'

def query_current_domain():
    headers = {
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {ACCESS_TOKEN}',
    }
    payload = {
        'query': '{ currentDomain { uuid, name, hostNames } }',
    }
    response = requests.post(
        f'https://{DOMAIN_SLUG}.api.drivr.cloud/graphql',
        headers=headers,
        json=payload
    )
    response.raise_for_status()
    return response.json()['data']['currentDomain']

try:
    current_domain = query_current_domain()
    print(current_domain)
except requests.exceptions.RequestException as error:
    print(error)

JavaScript Example

const fetch = require('node-fetch');

const ACCESS_TOKEN = 'YOUR_ACCESS_TOKEN_HERE';
const DOMAIN_SLUG = 'slug';

async function queryCurrentDomain() {
  const response = await fetch(`https://${DOMAIN_SLUG}.api.drivr.cloud/graphql`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${ACCESS_TOKEN}`,
    },
    body: JSON.stringify({ query: '{ currentDomain { uuid, name, hostNames } }' }),
  });

  const { data, errors } = await response.json();

  if (errors) {
    console.error(errors);
    throw new Error('GraphQL Query Failed');
  }

  return data.currentDomain;
}

(async () => {
  try {
    const currentDomain = await queryCurrentDomain();
    console.log(currentDomain);
  } catch (error) {
    console.error(error);
  }
})();

By using the authentication flows described in this guide, you can securely access DRIVR's GraphQL and REST APIs. Choose the flow that best suits your application's needs and follow the examples to integrate it seamlessly.