Authentication

Overview

Every API request carries a token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

How you get that token depends on whose account the requests act on.

Personal access token

Your own scripts, backups and tools, working on your own account.

OAuth application

An application other Drime users connect to. They approve it on Drime, and you never see their password.

Never ask a user for their Drime password. If your application works on other people’s accounts, use OAuth.

Personal access tokens

Create a token

Sign in to Drime.
Open Settings and go to Developers, or use the direct link.
Under API access tokens, click Create token.
Give it a name you will recognize later, for example the machine or the script that uses it.
Choose its Permissions (see below) and click Create.
Copy the token and store it somewhere safe. It is shown once: after you close the dialog, nobody can display it again, not even Drime.

Permissions

The dialog offers three choices:

Choice	What the token can do
All	Everything your account can do through the API. This is the default, so change it if you do not need everything.
Read Only	Read every resource in the list below. It cannot create, change or delete anything.
Restricted	Only what you pick, resource by resource: No Access, Read or Write. Write includes read.

The resources are Files, Folders, Sharing, Workspaces, Vault, Sign, Whiteboards, File requests, Send & Track, Contacts, Tags and Analytics (read only). They are the same scopes OAuth applications use, files.read, files.write and so on, and the scopes page lists the routes each one opens.

Give each token the narrowest permissions that work. A token that can only read your files cannot delete them if it leaks.

A token with Read Only or Restricted permissions never reaches the routes that manage the account itself, whatever you tick: API tokens, sessions, password and two-factor settings, billing and the admin area. Routes that belong to no resource are refused too, so a limited token cannot be used to create a more powerful one. Any token can read GET /users/me, whatever its permissions.

Vault files stay encrypted. With Vault access, a token lists and downloads encrypted data. Only the vault password, on your side, can decrypt it.

Lifetime and revocation

A personal access token does not expire. It works until you delete it. The API access tokens list shows when each token was last used. Delete a token from the same list as soon as you stop using it, or straight away if it may have leaked: it stops working immediately.

Using the token

Send it in the Authorization header of every request:

curl https://app.drime.cloud/api/v1/users/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch('https://app.drime.cloud/api/v1/users/me', {
  headers: {
    'Authorization': `Bearer ${process.env.DRIME_API_TOKEN}`
  }
});

const { user } = await response.json();
console.log(user.email);

import os
import requests

response = requests.get(
    'https://app.drime.cloud/api/v1/users/me',
    headers={'Authorization': f"Bearer {os.environ['DRIME_API_TOKEN']}"}
)

print(response.json()['user']['email'])

Response

{
  "user": {
    "id": 15843,
    "email": "you@example.com",
    "display_name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  },
  "status": "success"
}

Error Responses

401 Unauthorized

The token is missing, wrong, or was deleted:

{
  "message": "Unauthenticated."
}

403 Forbidden

The token is valid but its permissions do not cover this route. The message names the missing scope:

{
  "message": "This API key is missing the required scope: files.write"
}

Routes a limited token can never reach answer:

{
  "message": "This endpoint cannot be accessed with a restricted API key."
}

And when the token is fine but your account itself may not do this, for example on a file someone shared with you read only:

{
  "message": "This action is unauthorized."
}

Keeping tokens safe

Environment variables

Keep tokens out of your code and out of version control

One token per tool

Delete one without breaking the others, and see which one was used last

Narrow permissions

Read Only or Restricted whenever All is not needed

Never in a shipped app

Anything inside a browser page or an app you distribute can be extracted. Use OAuth there

Example: Setting Up Environment Variables

Linux/macOS
Windows (PowerShell)
.env File

export DRIME_API_TOKEN="your_token_here"

$env:DRIME_API_TOKEN = "your_token_here"

DRIME_API_TOKEN=your_token_here

Then use it in your code:

const token = process.env.DRIME_API_TOKEN;

fetch('https://app.drime.cloud/api/v1/users/me', {
  headers: {
    'Authorization': `Bearer ${token}`
  }
});

Get Started

OAuth Applications

Overview

Personal access token

OAuth application

Personal access tokens

Create a token

Permissions

Lifetime and revocation

Using the token

Error Responses

401 Unauthorized

403 Forbidden

Keeping tokens safe

Environment variables

One token per tool

Narrow permissions

Never in a shipped app

Example: Setting Up Environment Variables

​Overview

Personal access token

OAuth application

​Personal access tokens

​Create a token

​Permissions

​Lifetime and revocation

​Using the token

​Error Responses

​401 Unauthorized

​403 Forbidden

​Keeping tokens safe

Environment variables

One token per tool

Narrow permissions

Never in a shipped app

​Example: Setting Up Environment Variables

Overview

Personal access tokens

Create a token

Permissions

Lifetime and revocation

Using the token

Error Responses

401 Unauthorized

403 Forbidden

Keeping tokens safe

Example: Setting Up Environment Variables