This guide will help you understand how to authenticate your requests with Drivly’s APIs. The Drivly API ecosystem uses both API Keys, and JSON Web Tokens (JWT) for authentication.

​
API Keys vs. JWT Tokens

API Keys should be treated like a password for your account. They can be used to grant access to all the resources in your account. They are powerful, and must be kept secret.

JWT Tokens, on the other hand, are used to authenticate a specific user. They have an expiration time, and permissions are baked into the token itself to prevent unauthorized access.

We recommend using JWT tokens for your applications, using least-privilege principles to ensure that your applications are secure.

​
API Keys

For security purposes, you cannot create API Keys via the API. However, you can create them in the Drivly dashboard. Once you’ve created an API key, you can use it to authenticate your requests by including it in the Authorization header.

Using an API Key
curl -X GET \
  https://commerce.driv.ly/api/invoices \
  -H 'Authorization: Bearer apiKey'

​
JWT Tokens

JWT Tokens are used to authenticate a specific user. You can create a JWT Token by sending a POST request to the /auth endpoint.

Creating a JWT Token
curl -X POST \
  https://commerce.driv.ly/api/auth \
  -H 'Authorization: Bearer apiKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "permissions": [
      "invoices.read",
      "services.read"
    ]
  }'
JWT Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expires": "2024-01-01T00:00:00Z"
}

​
JWT Token Parameters

​
permissions
string[]

An array of permissions that the token should have. Any permission ending in .read will grant GET access to the resource, while any permission ending in .write will grant POST, PUT, and DELETE access to the resource.

​
expires
string

The expiration date of the token. After this date, the token will no longer be valid.

By default, this will be set to 1 year from the current date.

​
User Sessions

If you use our JS SDK, you wont need to worry about refreshing user sessions. The SDK will automatically handle this for you.

There are some cases where you may need to authenticate a user, such as storing sensitive information (SSN, credit card numbers, etc). For such cases, you can redirect the user to the /auth endpoint, where they can log in and grant your application access to their account.

Creating a user session
curl -X POST \
  https://commerce.driv.ly/api/auth \
  -H 'Authorization: Bearer apiKey' \
  -H 'Content-Type: application/json' \
  -d '{
    "permissions": [
      "invoices.read",
      "services.read"
    ],
    "redirect": "https://yourapp.com/auth/callback"
  }'
Response
{
  "redirect": "https://commerce.driv.ly/auth?token=eyJhb...
}

Once the user has logged in, they will be redirected back to your application with both a JWT token, and a refresh token:

User is redirected
GET /auth/callback?token=eyJhg...&refresh=ruurMeRWopJTGNWOPdfDQRHkvBwkikjAQp

​
Managing a User Session

The JWT Token can be used to make requests, while the refresh token is used to fetch a new JWT once the current one expires.

The JWT is only valid for 10 minutes after creation, however the refresh token lasts forever.

Refreshing a JWT Token
curl -X GET \
  https://commerce.driv.ly/api/auth/refresh \
  -H 'Authorization: JWT token'
Response
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "refresh": "iYthyYuIBdDUkgcMvfWK",
  "expires": "2024-01-01T00:00:00Z"
}

​
Why use User Sessions?

For applications that deal with sensitive information, user sessions are a great way to pass information to Drivly, without your servers needing to be compliant with data protection laws. This is because the user is sending their information directly to us from their own browser, and not through your servers.

Any information the user provides is stored in your dashboard, and can be accessed by you at any time. However, there are limitations (SSNs, credit card numbers, etc), and we recommend using the least-privilege principle when requesting permissions from the user.