Authentication

The SimpleDocs API uses OAuth 2.0 with the client credentials grant. This means your server exchanges a client_id and client_secret for a short-lived Bearer token, then sends that token with every API request.

Prerequisites

You’ll need an OAuth application linked to your company. Your SimpleDocs administrator can create one from the admin panel or by contacting the SimpleDocs team. You will receive:

Client ID — your application’s public identifier
Client Secret — a secret key (keep this safe, never expose it client-side)

Step 1: Request an access token

The token endpoint is rate-limited to 10 requests per minute per IP address — stricter than the general API limit. Cache your tokens rather than requesting a new one for every call.

Make a POST request to the token endpoint:

curl -X POST https://app.simpledocs.com/api/oauth/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=read write"

A successful response looks like:

{
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "scope": "read write",
  "created_at": 1709654400
}

Field	Description
`access_token`	The Bearer token to use in requests.
`expires_in`	Token lifetime in seconds (2 hours).
`scope`	The granted scopes.

Scopes

Scope	Grants access to
`read`	All `GET` endpoints.
`write`	Create endpoints (`POST`) for documents, requests, and webhooks.
`read write`	Both read and write access.

You can omit scope if you only need read access and your OAuth application is scoped to read or write — it defaults to read. If your application has the read write scope, you must specify scope explicitly.

Step 2: Use the token

Include the token in the Authorization header of every API request:

curl https://app.simpledocs.com/api/v1/workflows \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Token expiry and renewal

Tokens expire after 2 hours (7200 seconds). When a token expires, the API returns:

{
  "type": "token_expired",
  "status": 401,
  "title": "Token Expired",
  "detail": "The access token has expired."
}

To continue making requests, request a new token using the same client credentials. There is no refresh token flow — simply repeat Step 1.

Token revocation

Each time you request a new token, the previous token for the same application is automatically revoked. Only one active token per OAuth application is allowed at any time. You can also explicitly revoke a token:

curl -X POST https://app.simpledocs.com/api/oauth/revoke \
  -d "token=YOUR_ACCESS_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Best practices

Cache tokens until they are close to expiring, rather than requesting a new token for every API call.
Store credentials securely — never embed your client secret in client-side code, mobile apps, or public repositories.
Request only the scopes you need — if your integration only reads data, omit the write scope.

Error responses

Status	Type	Meaning
401	`token_expired`	The token has expired. Request a new one.
401	`token_revoked`	The token was revoked (a newer token was issued or it was explicitly revoked).
401	`invalid_token`	The token is not recognized.
401	`invalid_client`	The client ID or secret is incorrect.
403	`insufficient_scope`	The token doesn’t have the required scope for this endpoint.

Getting Started

Guides

Prerequisites

Step 1: Request an access token

Scopes

Step 2: Use the token

Token expiry and renewal

Token revocation

Best practices

Error responses

​Prerequisites

​Step 1: Request an access token

​Scopes

​Step 2: Use the token

​Token expiry and renewal

​Token revocation

​Best practices

​Error responses

Prerequisites

Step 1: Request an access token

Scopes

Step 2: Use the token

Token expiry and renewal

Token revocation

Best practices

Error responses