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 / Management	Organisations, workspaces, and settings on the capture side. Moving to the Management API.
idp.capture	Docmind	Deprecated name for capture. Keycloak still issues this string today. Treat it as docmind.capture.
docbooks.onboarding	Docbooks	Create and offboard organisations and workspaces (until Management API)
docbooks.bookings	Docbooks	Booking runtime and booking feedback

Booking submit also needs capture on the same token (forwarded to the extractor). See Enable capture and booking.

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

Environment	Product	Base URL
Stage	Docmind	https://idp-stage.docpier.com/api/v1
Production	Docmind	https://idp.docpier.com/api/v1
Stage	Docbooks	https://stage.docpier.io/api/docbooks/v1
Production	Docbooks	https://docpier.io/api/docbooks/v1

Identity provider (Keycloak)

Tokens are minted by Keycloak, not by the product APIs.

Environment	Token URL
Docmind stage	https://auth-stage.docpier.com/realms/idp/protocol/openid-connect/token
Docmind production	https://auth.docpier.com/realms/idp/protocol/openid-connect/token
Docbooks stage	https://stage.docpier.io/auth/realms/idp/protocol/openid-connect/token
Docbooks production	https://docpier.io/auth/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=idp.capture"

Until Keycloak accepts docmind.capture, request idp.capture on the token URL. The permission is the same.

Docbooks

curl -X POST 'https://stage.docpier.io/auth/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.onboarding'

Response

200

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