Authentication

Both live partner APIs use OAuth 2.0 client credentials (server-to-server). The token is bound to the Partner; you never send partnerId in bodies. End users do not log in to Docpier.

POST/realms/idp/protocol/openid-connect/token

Tip

Cache tokens and refresh before expires_in (typically 300 seconds). Request only the scopes you need. Never commit client_secret.

Token request

Content-Typestringheaderrequired

application/x-www-form-urlencoded

grant_typestringbodyrequired

Always client_credentials.

client_idstringbodyrequired

Issued by Docpier. Email support@docpier.com.

client_secretstringbodyrequired

Partner secret for this client.

scopestringbodyrequired

Space-separated scopes.

Scopes

Scope	Product	Purpose
docmind.capture	Docmind	Extract documents: read and write workspace documents
docmind.onboarding	Docmind	Organisations, workspaces, and settings on the Docmind side (until Management API)
idp.capture	Docmind	Deprecated name for docmind.capture, still accepted. Request docmind.capture for new clients.
docbooks.onboarding	Docbooks	Create and offboard organisations and workspaces (until Management API)
docbooks.bookings	Docbooks	Booking runtime and booking feedback

Submitting and reading a booking need docmind.capture on the same token as docbooks.bookings — Docbooks forwards the token to Docmind. See Combine analysis and booking.

Onboarding needs docmind.onboarding on the same token as docbooks.onboarding. Keycloak does not grant either Docmind scope automatically — request it explicitly alongside the Docbooks scope.

A bookings-only token cannot onboard.

Calling the API

Authorizationstringheaderrequired

Bearer <access_token>

401 and 403 responses have no body. Retry 401 after refreshing the token.

API hosts

Product	Stage	Production
Docmind	https://idp-stage.docpier.com/api/v1	https://idp.docpier.com/api/v1
Docbooks	https://stage.docpier.io/api/docbooks/v1	not yet available

Identity provider (Keycloak)

Tokens are minted by Keycloak, not by the product APIs. One realm, idp, serves both products — the same token URL, whichever API you call.

Environment	Token URL
Stage	https://auth-stage.docpier.com/realms/idp/protocol/openid-connect/token
Production	https://auth.docpier.com/realms/idp/protocol/openid-connect/token

Note

Paste a stage token into Try It. Keep Stage selected. Try It servers are the origin (https://idp-stage.docpier.com/api, https://stage.docpier.io) because /v1 is already on the operation path.

Request

Docmind

curl -X POST https://auth-stage.docpier.com/realms/idp/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=docmind.capture"

A token carrying the deprecated idp.capture is still accepted — the permission is the same. Request docmind.capture for new clients.

Docbooks

curl -X POST 'https://auth-stage.docpier.com/realms/idp/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=$CLIENT_ID' \
  -d 'client_secret=$CLIENT_SECRET' \
  -d 'scope=docbooks.bookings docmind.capture'

docbooks.bookings is the runtime scope — submitting documents and reading bookings. docbooks.onboarding is only for creating and retiring organisations and workspaces.

Response

200

{
    "access_token": "eyJhbGciOi...",
    "expires_in": 300,
    "token_type": "Bearer",
    "scope": "docmind.capture"
}