Skip to main content
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

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.

​
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.
401invalid_clientThe client ID or secret is incorrect.
403insufficient_scopeThe token doesn’t have the required scope for this endpoint.