Authentication

OAuth 2.0 authorization code flow used by the Pipedream integration.

Overview

Minform issues access tokens as HS256 JWTs signed with the OAuth client secret. The JWT includes a pipedream claim (clientId + scopes). All /api/pipedream/* routes verify that claim.

Flow is standard authorization code (not PKCE). Scopes granted on consent are always read:forms and read:submissions.

Flow

Pipedream redirects the user to Minform's authorize page with client_id, redirect_uri, response_type=code, and state.
User signs in and approves access.
Minform redirects to redirect_uri with code and state.
Pipedream exchanges the code at the token endpoint for access_token + refresh_token.
API calls send Authorization: Bearer <access_token>.

Endpoints

Authorize (user consent UI)

Browser page — not an /api JSON route.

GET https://minform.io/oauth/authorize

Query param	Required	Notes
`client_id`	Yes	Registered OAuth client
`redirect_uri`	Yes	Must match a URI allowlisted on the client
`response_type`	Yes	Must be `code`
`state`	Yes	CSRF / correlation token
`scope`	No	Accepted by the UI; granted scopes are fixed server-side

Token

POST https://minform.io/api/oauth/token

Accepts application/x-www-form-urlencoded or application/json.

Authorization code

grant_type=authorization_code
code=...
client_id=...
client_secret=...
redirect_uri=...

Refresh token

Same URL — there is no separate /oauth/refresh route.

grant_type=refresh_token
refresh_token=...
client_id=...
client_secret=...

Success response

{
  "access_token": "<jwt>",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "<opaque>"
}

Access tokens expire in 1 hour. Refresh returns a new access token (same refresh token value is returned on refresh).

Revoke

POST https://minform.io/api/oauth/revoke

Clears the refresh token for the client. Body fields: token (refresh token), client_id, client_secret.

{ "success": true }

Calling the API

Authorization: Bearer <access_token>

Use tokens issued for the Pipedream OAuth client (JWT must include pipedream.clientId). Send them only to /api/pipedream/* endpoints.