Skip to main content

Documentation Index

Fetch the complete documentation index at: https://formhug.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

All authenticated FormHug API endpoints expect a bearer token in the Authorization header: 
Authorization: Bearer <token>
FormHug supports two kinds of token. Both enforce the same scope system — each endpoint’s reference page lists its required scope.

​
Personal Access Token (PAT)

Use this for server-to-server scripts, internal tools, or anywhere running a full OAuth flow would be overkill. A PAT belongs to a single user and is prefixed with fh_: 
Authorization: Bearer fh_xxxxxxxxxxxx
Generate a PAT at formhug.ai/profile/personal_access_token and assign only the scopes the integration actually needs.
The interactive Try it out panel in this reference uses Personal Access Tokens. Paste your fh_… token into the Authorization box to call live endpoints from the browser.
Treat a PAT like a password. Store it in a secret manager, never commit it to source control, and rotate it if it leaks.

​
OAuth 2.0 access token (JWT)

Use OAuth when a third-party application acts on a FormHug user’s behalf. FormHug implements the Authorization Code flow with PKCE (RFC 7636).
  1. Generate a code_verifier and derive a code_challenge using the S256 method.
  2. Redirect the user to GET /api/v1/oauth/authorize with your client_id, redirect_uri, requested scope, state, code_challenge, and code_challenge_method=S256.
  3. The user is redirected back to your redirect_uri with a one-time code.
  4. Exchange the code at POST /api/v1/oauth/token with grant_type=authorization_code, the code, and the original code_verifier. You receive an access_token (JWT), a refresh_token, expirations, and the granted scope.
  5. Call API endpoints with the JWT in the Authorization header.
  6. When the access token expires, call /api/v1/oauth/token again with grant_type=refresh_token and your refresh_token.
  7. Revoke a token with POST /api/v1/oauth/revoke (RFC 7009). This also clears the underlying session.
See the OAuth section in the sidebar for full endpoint details, parameters, and error responses.
OAuth tokens are documented here for reference. The Try it out flow in this UI doesn’t run an OAuth handshake — use a Personal Access Token to send live requests from the playground.

​
Scopes

Every endpoint requires a specific scope. Both PATs and OAuth tokens are checked against the same scope list:
ScopeGrants
form:readRead forms and folders.
form:writeCreate and update forms and folders.
form:deleteDelete forms and folders.
entry:readRead submissions to a form.
entry:writeCreate or modify entries on the owner’s behalf.
form:respondSubmit to a published form on a respondent’s behalf.
integration:readList webhooks and other integrations.
integration:writeConfigure webhooks and other integrations.
A request with an insufficient scope returns 403 Forbidden. A request with a missing or invalid token returns 401 Unauthorized.
Last modified on May 15, 2026