Authentication

OAuth 2.0 client credentials, and nothing else. Any standard OAuth client library will do this without being told anything about us.

curlJavaScriptPython

Getting a token#

OAuth 2.0 client credentials (RFC 6749 §4.4). Send your client id and secret, get a bearer token that lasts one hour. Any standard OAuth client library will do this without being told anything about us.

Credentials are made on your API access page. Ask for a token when you need one and keep it until it expires — a token per call is a thousand round trips you do not need.

Keep the token exchange on your server. A client secret in a browser bundle, a mobile app or a public repository is a credential somebody else has. Client credentials is the grant for your software talking to us — there is no flow here for a page talking to us on a visitor's behalf, because there is no third party and nothing to delegate.

Form fields
`grant_type`	required	Must be `client_credentials`. It is the only grant this endpoint issues.
`client_id`	required	From your API access page. Can also be sent as HTTP Basic, which is what most OAuth libraries do.
`client_secret`	required	The secret shown once when the credential was made.
`scope`	optional	Space separated, to ask for LESS than the credential holds. Asking for more is ignored rather than refused.

POST/auth/oauth/token

curl -s https://docubend.com/auth/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=$DOCUBEND_CLIENT_ID \
  -d client_secret=$DOCUBEND_SECRET

POST/auth/oauth/token

const BASE = "https://docubend.com";

async function token() {
  const r = await fetch(`${BASE}/auth/oauth/token`, {
    method: "POST",
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: process.env.DOCUBEND_CLIENT_ID,
      client_secret: process.env.DOCUBEND_SECRET,
    }),
  });
  if (!r.ok) throw new Error(`token: ${r.status}`);
  return (await r.json()).access_token;
}

const TOKEN = await token();

POST/auth/oauth/token

import os, requests

BASE = "https://docubend.com"

def token():
    r = requests.post(f"{BASE}/auth/oauth/token", data={
        "grant_type": "client_credentials",
        "client_id": os.environ["DOCUBEND_CLIENT_ID"],
        "client_secret": os.environ["DOCUBEND_SECRET"],
    }, timeout=30)
    r.raise_for_status()
    return r.json()["access_token"]

TOKEN = token()

Response

200

{
  "access_token": "dbt_EXAMPLEtokenNOTaREALoneQmZ7x2Kv9pR4sT6uW8yA",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "documents:read documents:write"
}

Why not three-legged OAuth. Because nobody is delegating anything. The thing on the other end is your own software acting for your own account — there is no third party, no consent to obtain and no other user's data in reach. An authorization-code flow would add redirect URIs, a consent screen and refresh tokens to answer a question nobody asked.

Scopes#

Two, and they are coarse on purpose. A scope per route reads like security and is really a maintenance burden nobody edits after the first day — the account's own capabilities behind it are the real limit.

Scope	Methods	What it covers
`documents:read`	`GET, HEAD`	List documents, fetch one, and download it as a PDF, an image, SVG, mermaid, .drawio or its own model.
`documents:write`	`POST, PUT, PATCH, DELETE`	Create documents, replace what is in them, place form fields, collect answers, and delete.

Scope is enforced by HTTP method, not by a list of routes. Anything that only reads is a read and everything else is a write, so a route added tomorrow is covered on the day it is added, and covered the safe way round.

Six rules#

The secret is shown once	What is stored is a SHA-256 of it. A leaked table must not be a pile of live keys, so “we cannot show it to you again” is true rather than a policy.
A token lasts one hour	Long enough that a batch job does not spend its life at the token endpoint; short enough that a token scraped out of a log is usually already dead.
The plan is checked on every call	Not only when the token was issued. A subscription that lapses stops the integration within the hour without anybody deleting a credential.
Scopes are a ceiling, never a floor	A token can ask for less than its credential holds and never for more, and narrowing a credential bites the tokens already out there.
Revoking kills the tokens with it	Anything else means “revoked” has an hour-long asterisk on it.
Rotation leaves the old secret live for 24 hours	There is no order in which a new secret reaches every worker, container and cron entry without a gap. The window is what you deploy in. The it-got-out case has its own button and no window.

Browser or credential, never both#

A browser session cannot reach /api/v1 and a credential cannot reach anything else. Both are refused in one place, and both refusals say which door you are at.

Nothing in the docubend web app calls this API — the workspace has its own routes — so accepting a signed-in session here would buy nothing and leave a cookie-authenticated write surface for a cross-site form to aim at.

You are	You reach	Anything else answers
A signed-in browser session	`/api/…`, the workspace routes	`401` at `/api/v1`
A bearer token	`/api/v1/…`	`404` anywhere else

Start

Reference

Details

Authentication

Getting a token#

Response

Scopes#

Six rules#

Browser or credential, never both#