OAuth 2.0 Authentication

In addition to the appkey header, Re:port 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 should I use OAuth instead of appkey?

If you are only automating your own workspace, appkey is the shortest path. OAuth exists for server-to-server delegation (Client Credentials) and for external services that must ask another user for authorisation (Authorization Code + PKCE).

Use case	Recommended method
Single-workspace automation (cURL, internal batch jobs)	appkey header
Server-to-server integration (backend → Re:port 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. Also required by the webhook endpoint management API (list, create, update, delete, regenerate secret) — see Webhook notifications

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.

APIs that require workspace membership are out of reach

A token from this grant has no end user — its subject is the client itself — so no workspace membership row can be resolved for it. Any API that checks membership or role returns 403 even when the token has the right scopes. Webhook endpoint management, for example, cannot be called at all — not even listing.

For operations that need per-user permissions, use a token from the Authorization Code flow (above). Workspace-level APIs such as PDF generation work fine with this grant.

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