Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.simpledocs.com/llms.txt

Use this file to discover all available pages before exploring further.

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
}
FieldDescription
access_tokenThe Bearer token to use in requests.
expires_inToken lifetime in seconds (2 hours).
scopeThe granted scopes.

​
Scopes

ScopeGrants access to
readAll GET endpoints.
writeCreate endpoints (POST) for documents, requests, and webhooks.
read writeBoth 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

StatusTypeMeaning
401token_expiredThe token has expired. Request a new one.
401token_revokedThe token was revoked (a newer token was issued or it was explicitly revoked).
401invalid_tokenThe token is not recognized.
401invalid_clientThe client ID or secret is incorrect.
403insufficient_scopeThe token doesn’t have the required scope for this endpoint.