OAuth 2.0 Authentication

In addition to the appkey header, Report Flow API supports OAuth 2.0 / OpenID Connect. This is intended for third-party integrations (Make.com, etc.) and custom apps that need a per-user authorization flow or server-to-server delegation.

When to use which method

Use case	Recommended method
Single-workspace automation (cURL, internal batch jobs)	appkey header
Server-to-server integration (backend → Report Flow)	OAuth 2.0 Client Credentials
Per-user authorization (Make.com, third-party SaaS, personal apps)	OAuth 2.0 Authorization Code + PKCE

Endpoints

We recommend pulling the OIDC discovery document at runtime:

GET https://re-port-flow.com/api/v1/.well-known/openid-configuration

Important: The OAuth flow (Discovery / Authorize / Token / UserInfo) is hosted on re-port-flow.com/api/v1, which is a different host from the protected resource API (api.re-port-flow.com/v1/...). The bearer token issued by the OAuth flow is sent to the protected resource API.

Main endpoints:

Item	URL
Issuer	https://re-port-flow.com/api/v1
Authorization	${issuer}/oauth/authorize
Token	${issuer}/oauth/token
UserInfo	${issuer}/oauth/userinfo
Protected resource API (target of Bearer)	https://api.re-port-flow.com/v1/...

Supported parameters

Item	Value
response_type	code
grant_types	authorization_code, refresh_token, client_credentials
code_challenge_method	S256 (PKCE required)
token_endpoint_auth_methods	none, client_secret_post, client_secret_basic
Access token TTL	3600 seconds (1 hour)

Scopes

Scope	Description
openid	Confirms the user's id (OIDC)
profile	Profile info (this implementation includes the email address)
designs:read	Read designs (list and detail)
designs:write	Create and edit designs
templates:read	Read templates (list and detail)
templates:write	Create and edit templates
pdf:generate	Generate PDFs from a template

Multiple scopes are space-separated (e.g. pdf:generate designs:read).

Client types

Type	is_public	Authentication	Typical use
Public Client	true	PKCE only (no client_secret)	Mobile/SPA, public integrations such as Make.com
Confidential Client	false	client_secret required	Server-to-server, client_credentials grant

The client_credentials grant is for confidential clients only. Public clients cannot use it.

---

Authorization Code flow (PKCE)

Use this flow when each end user authorizes the app individually — for example Make.com integrations or apps where the user operates on their own workspace.

1. Authorization request

GET https://re-port-flow.com/api/v1/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://your-app.example.com/callback
  &scope=openid%20profile%20pdf:generate
  &state=RANDOM_STATE
  &code_challenge=BASE64URL(SHA256(verifier))
  &code_challenge_method=S256

After the user signs in and consents, the browser is redirected to your redirect_uri with code and state query parameters.

2. Token request

POST https://re-port-flow.com/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https://your-app.example.com/callback
&client_id=YOUR_CLIENT_ID
&code_verifier=ORIGINAL_VERIFIER

Response:

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_...",
  "scope": "openid profile pdf:generate"
}

For confidential clients, also send client_secret (using client_secret_post) or place credentials in a Basic auth header (client_secret_basic).

3. Refresh token

POST https://re-port-flow.com/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=rt_...
&client_id=YOUR_CLIENT_ID

---

Client Credentials flow

For server-to-server delegation. A registered confidential client obtains an access token for its own workspace, with no end user involved.

Token request

POST https://re-port-flow.com/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(client_id:client_secret)

grant_type=client_credentials
&scope=pdf:generate%20templates:read

Or, using client_secret_post:

POST https://re-port-flow.com/api/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&scope=pdf:generate%20templates:read

Response (no refresh token is issued):

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "pdf:generate templates:read"
}

If scope is omitted, the full set of allowed_scopes registered for the client is granted.

---

Using the access token

Send the issued access token in an Authorization: Bearer header instead of the appkey header:

curl -X POST https://api.re-port-flow.com/v1/file/sync/single \
  -H "Authorization: Bearer eyJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{...}'

Error responses

The token endpoint follows RFC 6749 §5.2:

{
  "error": "invalid_client",
  "error_description": "Invalid client_secret"
}

Common error codes:

error	When
invalid_client	client_id / client_secret is invalid
invalid_grant	Authorization code or refresh token is invalid or expired
invalid_scope	Requested scope exceeds allowed_scopes
unauthorized_client	A public client requested client_credentials, etc.
unsupported_grant_type	Unsupported grant_type

Next steps

• API Keys — how to use the appkey header
• Authentication overview — choosing between methods
• PDF Generation Guide