Authentication

The Formable API authenticates requests using OAuth 2.0 client credentials. You exchange a client ID and client secret for a short-lived access token, then send that token as a Bearer token on every request.

Contact support@formabledocs.com to get API credentials for your organization. You’ll receive a client ID, a client secret, and the token URL and audience to use.

Get an access token

Request a token from your token URL using the client credentials grant. Pass the audience so the token is scoped to the Formable API.

curl --request POST \
  --url https://YOUR_TENANT.auth0.com/oauth/token \
  --header 'content-type: application/json' \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "https://formable-production.up.railway.app/api",
    "grant_type": "client_credentials"
  }'

const res = await fetch("https://YOUR_TENANT.auth0.com/oauth/token", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    client_id: process.env.FORMABLE_CLIENT_ID,
    client_secret: process.env.FORMABLE_CLIENT_SECRET,
    audience: "https://formable-production.up.railway.app/api",
    grant_type: "client_credentials",
  }),
});

const { access_token } = await res.json();

import os
import requests

res = requests.post(
    "https://YOUR_TENANT.auth0.com/oauth/token",
    json={
        "client_id": os.environ["FORMABLE_CLIENT_ID"],
        "client_secret": os.environ["FORMABLE_CLIENT_SECRET"],
        "audience": "https://formable-production.up.railway.app/api",
        "grant_type": "client_credentials",
    },
)

access_token = res.json()["access_token"]

A successful response returns an access token and its lifetime in seconds:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Use the token

Include the access token in the Authorization header of every API request.

curl --request GET \
  --url https://formable-production.up.railway.app/api/v0/signature-requests \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Cache the access token and reuse it until it expires rather than requesting a new one per call. Refresh it when you receive a 401 response.

Base URLs

https://formable-production.up.railway.app/api

http://localhost:4000/api

All endpoints are versioned under /v0, so a full URL looks like https://formable-production.up.railway.app/api/v0/signature-requests.

Authorization errors

Requests fail with a 401 when the bearer token is missing, malformed, or expired:

{
  "error": "Auth token not valid"
}

A 403 means the token is valid but your organization isn’t authorized for the resource — for example, creating an edit URL for a template that belongs to another organization.

Never expose your client secret in browser or mobile code. Request tokens from a backend service, and only pass short-lived signing and redline URLs to the client.

Getting Started

Workflows

Get an access token

Use the token

Base URLs

Authorization errors

​Get an access token

​Use the token

​Base URLs

​Authorization errors

Get an access token

Use the token

Base URLs

Authorization errors