Overview

If you've set up a DRIVR domain and want to get started right away, this guide is for you. Here we don't go into all types of authentication, but only the simplest: Resource Owner Password Credentials. With this we will create a Connector Token in this guide, which you can then use directly to start using the GraphQL API or the REST APIs.

For a full list and more detailed description of all authentication methods, please check out the Authentication Getting Started Guide. There you will find all the information you need for more advanced use cases.

Prerequisites

In order to follow this guide successfully, you need a DRIVR domain. If you don't have one yet, you can create one for free here.

By default, DRIVR domains are created with password authentication. This means that you can log in to DRIVR with your username and password. If the password authentication 'DefaultAuthenticationMethod' is turned off, this guide will not work. This may be the case if you use other authentication methods like Google or Azure.

Create an ApplicationConsumer

An ApplicationConsumer represents an application that wants to access the DRIVR APIs. We can create the ApplicationConsumer either via DRIVR UI or via GraphiQL:

Create an ApplicationConsumer via DRIVR UI

After logging into DRIVR UI click on Settings in the upper left corner and then on Application Consumers. Now click on Add ApplicationConsumer.

Set a name and the slug. For Grant Type select the type Password. As Scope we enter email. Enter a secure key for Secret (similar to a password, this will be needed later) and create the ApplicationConsumer with a click on Create. The ApplicationConsumer is now displayed in the table together with the identifier. This will also be needed later.

Create an ApplicationConsumer via GraphiQL

Open GraphiQL and run the following mutation, adjusting the values accordingly:

mutation createApplicationConsumer {
  createApplicationConsumer(
    name: "my-new-app",
    slug: "my-app",
    secret: "**************",
    grantTypes: [
        PASSWORD
    ],
    scopes: [
        "email"
    ]
  ) {
    uuid
    name
    identifier
    status
  }
}

{
  "data": {
    "authenticationMethods": {
      "items": [
        {
          "uuid": "493f1186-59b0-46de-b692-812dd08fe931",
          "authenticationType": "DEFAULT",
          "status": "ACTIVATED"
        }
      ],
      "limit": 1000,
      "totalItems": 1
    }
  }
}

Make a note of the identifier and the set secret. These will be needed in the second step.

Create a MachineUser

With this information we could already generate a User Token, which can be used to perform actions on behalf of you as a user. However, we want to create a Connector Token here, so we need a MachineUser. This represents a machine that can perform actions on behalf of a user. We can create the MachineUser via GraphiQL:

mutation createMachineUser {
  createMachineUser (
    username: "my-machine-user",
    password: "********"
  ) {
    uuid
    username
    roleAssignments {
      items {
        uuid
        role {
          name
        }
      }
    }
  }
}

{
  "data": {
    "createMachineUser": {
      "uuid": "dd33b1f8-2ba7-471b-aa70-e55302e46928",
      "username": "my-machine-user",
      "roleAssignments": {
        "items": []
      }
    }
  }
}

query getDomainAndConnectorRoleUuid {
  currentDomain {
    uuid
  }
  roles(name: "Connector") {
    items {
      uuid
    }
  }
}

{
  "data": {
    "currentDomain": {
      "uuid": "69973a77-6264-4dcc-83ab-2bae466c3a6f"
    },
    "roles": {
      "items": [
        {
          "uuid": "4044677c-a017-4f11-b322-02b1d8830942"
        }
      ]
    }
  }
}

mutation createMachineUser {
  createRoleAssignment(
    assigneeUuid: "${UUID of MachineUser we created above}",
    roleUuid: "${UUID of the Connector Role}",
    entityUuid: "${UUID of the Domain we got above}"
  ) {
    uuid
  }
}

{
  "data": {
    "createRoleAssignment": {
      "uuid": "9f91efb1-3648-4ec6-aae9-188346730ad5"
    }
  }
}

curl -sX "POST" "https://{slug}.api.drivr.cloud/authenticate/token?grant_type=password" \
    -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \
    --data-urlencode "client_id=my-new-app.{slug}.api.drivr.cloud" \
    --data-urlencode "client_secret=************" \
    --data-urlencode "username=machine-user-username" \
    --data-urlencode "password=************"

{
  "access_token": "7TIahRdjqCxlHjnl5GYTSPdjSvxQpnV24za2lLolNl",
  "expires_in": 864000,
  "token_type": "Bearer"
}