Home/Authentication

Authentication

Learn how to authenticate with the Minform API.

Overview

Minform uses OAuth 2.0 for API authentication. This is the same authentication method used by the Pipedream integration, ensuring secure access to your form data.

OAuth 2.0 Authentication Flow

Our Pipedream integration uses the OAuth 2.0 authorization code flow. This method provides a secure way for users to grant Pipedream access to their Minform account without sharing credentials.

Authentication Flow

Authorization Request: Your application redirects the user to Minform's authorization endpoint with required parameters.
User Consent: The user logs in and grants permission to your application.
Authorization Code: Minform redirects back to your application with an authorization code (valid for 10 minutes).
Token Exchange: Your application exchanges the code for access and refresh tokens using your client credentials.
API Access: Your application uses the access token to make authenticated API requests.
Token Refresh: When the access token expires (after 1 hour), use the refresh token to get a new access token.

OAuth 2.0 Endpoints

Authorization URL

The authorization endpoint used to get user consent.

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

Parameters

Parameter	Type	Required	Description
`client_id`	string	Yes	Your application's client ID
`redirect_uri`	string	Yes	Callback URL registered for your application
`response_type`	string	Yes	Must be set to `code`
`state`	string	Yes	Random string to prevent CSRF attacks
`scope`	string	No	Space-separated list of requested permissions

Example Request

GET https://minform.io/oauth/authorize?client_id=your_client_id&redirect_uri=https://yourapp.com/callback&response_type=code&state=random_string&scope=read:forms read:submissions

Success Response

User is redirected to your redirect_uri with:

https://yourapp.com/callback?code=authorization_code&state=random_string

Error Response

If user denies access:

https://yourapp.com/callback?error=access_denied&error_description=User+denied+access&state=random_string

Token URL

Exchange authorization codes for access tokens or refresh existing tokens.

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

Authorization Code Exchange

Exchange an authorization code for an access token:

Parameters

Parameter	Type	Required	Description
`grant_type`	string	Yes	Must be `authorization_code`
`code`	string	Yes	Authorization code from callback
`client_id`	string	Yes	Your application's client ID
`client_secret`	string	Yes	Your application's client secret
`redirect_uri`	string	Yes	Same redirect URI used in authorization

Example Request

POST https://minform.io/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=auth_code_here&client_id=your_client_id&client_secret=your_client_secret&redirect_uri=https://yourapp.com/callback

Success Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "a1b2c3d4e5f6..."
}

Refresh Token Exchange

Use a refresh token to get a new access token:

Parameters

Parameter	Type	Required	Description
`grant_type`	string	Yes	Must be `refresh_token`
`refresh_token`	string	Yes	Valid refresh token
`client_id`	string	Yes	Your application's client ID
`client_secret`	string	Yes	Your application's client secret

Example Request

POST https://minform.io/api/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=a1b2c3d4e5f6...&client_id=your_client_id&client_secret=your_client_secret

Success Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "a1b2c3d4e5f6...",
  "token_type": "bearer",
  "expires_in": 3600
}

Error Responses

Invalid Client Credentials (401)

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Invalid Authorization Code (400)

{
  "error": "invalid_grant",
  "error_description": "Invalid or expired authorization code"
}

Invalid Refresh Token (400)

{
  "error": "invalid_grant",
  "error_description": "Invalid refresh token"
}

Revoke Token URL

Revoke a refresh token to invalidate access for your application.

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

Parameters

Parameter	Type	Required	Description
`token`	string	Yes	The refresh token to revoke
`client_id`	string	Yes	Your application's client ID
`client_secret`	string	Yes	Your application's client secret

Example Request

POST https://minform.io/api/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=a1b2c3d4e5f6...&client_id=your_client_id&client_secret=your_client_secret

Success Response

Returns success even if the token was not found (per OAuth 2.0 specification):

{
  "success": true
}

Error Responses

Missing Parameters (400)

{
  "error": "invalid_request",
  "error_description": "Missing required parameters"
}

Invalid Client Credentials (401)

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Server Error (500)

{
  "error": "server_error",
  "error_description": "Failed to process revocation request"
}

Note: Revoking a refresh token will invalidate all access tokens generated from it. Users will need to re-authorize your application to regain access.

Scopes

Scopes define the level of access that Pipedream has to your Minform account. The following scopes are available:

Scope	Description
`read:forms`	Access to list forms in your account
`read:submissions`	Access to view form submissions

Using Authentication with API Requests

When making API requests to Minform, include the access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Note: All API requests must use HTTPS. Requests using HTTP will be rejected.