# Formify OAuth API

**Canonical:** https://apis.io/apis/formify-eu/formify-eu-oauth-api/  
**Provider:** Formify — https://apis.io/providers/formify-eu/  
**Base URL:** https://docs-api.formify.eu/v1  
**Documentation:** https://developers.formify.eu/

Formify OAuth API is one of 10 APIs that [Formify](https://apis.io/providers/formify-eu/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include OAuth. The published artifact set on APIs.io includes an OpenAPI specification.

## OAuth 2.0 Authorization Code Grant Flow Formify uses OAuth 2.0 to allow third-party applications to access the API on behalf of users. This section provides a step-by-step guide to implementing the authorization flow. ### Prerequisites See the **[Getting Access](/guides/getting-access/)** guide for details, but in short you must: 1. Obtain your `client_id` and `client_secret`. 2. Register your application at [app.formify.eu](https://app.formify.eu) 3. Configure your `redirect_uri` (must match exactly what you registered) ### Authorization Flow #### Step 1: Redirect User to Authorization URL Redirect the user to Formify's authorization endpoint: ``` https://docs-api.formify.eu/v1/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=read%20write&state=RANDOM_STATE_STRING ``` **Parameters:** - `client_id` (required): Your application's client ID - `redirect_uri` (required): Where to redirect after authorization (must be registered) - `response_type` (required): Always use `code` for authorization code flow - `scope` (required): Space-separated list of permissions (`read`, `write`, or `read write`) - `state` (recommended): Random string to prevent CSRF attacks #### Step 2: User Authorizes Your Application The user sees a consent screen and approves your application's access to their Formify account. #### Step 3: Receive Authorization Code After approval, Formify redirects back to your `redirect_uri` with an authorization code: ``` https://your-app.com/callback?code=AUTH_CODE_HERE&state=RANDOM_STATE_STRING ``` **Important:** Verify that the `state` parameter matches what you sent in Step 1. #### Step 4: Exchange Code for Access Token Make a POST request to the token endpoint to exchange the authorization code for an access token: ```bash POST https://docs-api.formify.eu/v1/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=AUTH_CODE_HERE &redirect_uri=YOUR_REDIRECT_URI &client_id=YOUR_CLIENT_ID &client_secret=YOUR_CLIENT_SECRET ``` **Response:** ```json { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "def502004a1b2c3d...", "scope": "read write" } ``` #### Step 5: Use Access Token Include the access token in the `Authorization` header for all API requests: ```bash GET https://docs-api.formify.eu/v1/docs Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` ### Token Refresh Access tokens expire after the time specified in `expires_in` (typically 1 hour). Use the refresh token to obtain a new access token without requiring user interaction: ```bash POST https://docs-api.formify.eu/v1/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=refresh_token &refresh_token=YOUR_REFRESH_TOKEN &client_id=YOUR_CLIENT_ID &client_secret=YOUR_CLIENT_SECRET ``` **Response:** Same structure as the initial token response, including a new `refresh_token`. ### Scope - **`read`**: Allows reading documents, files, user info, and account settings - **`write`**: Allows creating/updating documents, uploading files, and modifying settings Request only the scopes your application needs. Users see which permissions you're requesting during authorization. ### Common Errors | Error | Description | Solution | |-------|-------------|----------| | `invalid_grant` | Authorization code expired or already used | Codes expire after 10 minutes. Start the flow again. | | `invalid_client` | Invalid client_id or client_secret | Verify your credentials in app.formify.eu | | `redirect_uri_mismatch` | redirect_uri doesn't match registered URI | Must match exactly (including trailing slash) | | `invalid_scope` | Requested scope not allowed | Use only `read` and/or `write` | | `access_denied` | User denied authorization | User must approve for your app to work | ### Security Best Practices - **Never expose** `client_secret` in client-side code - **Always use HTTPS** for redirect URIs - **Validate state parameter** to prevent CSRF attacks - **Store tokens securely** (encrypted database, secure session storage) - **Refresh tokens proactively** before they expire to avoid service interruption

## Operations (4)

| Method | Path | Summary |
|---|---|---|
| GET | `/oauth` | OAuth authorize URL (browser redirect, not an API request) |
| POST | `/oauth/token` | Generate OAuth 2.0 access token using authorization code or refresh token |
| POST | `/oauth/revoke` | Revoke OAuth 2.0 token and its associated grant |
| POST | `/oauth/register` | Dynamic Client Registration (RFC 7591) |

## Machine-readable artifacts (1)

- **OpenAPI** — https://artifacts.apis.io/formify-eu/openapi/formify-eu-oauth-api-openapi.yml

## Other Formify APIs (9)

- [Formify Account API](https://apis.io/apis/formify-eu/formify-eu-account-api/)
- [Formify Auth API](https://apis.io/apis/formify-eu/formify-eu-auth-api/)
- [Formify Docs API](https://apis.io/apis/formify-eu/formify-eu-docs-api/)
- [Formify Drafts API](https://apis.io/apis/formify-eu/formify-eu-drafts-api/)
- [Formify Files API](https://apis.io/apis/formify-eu/formify-eu-files-api/)
- [Formify Links API](https://apis.io/apis/formify-eu/formify-eu-links-api/)
- [Formify Templates API](https://apis.io/apis/formify-eu/formify-eu-templates-api/)
- [Formify User API](https://apis.io/apis/formify-eu/formify-eu-user-api/)
- [Formify Webhooks API](https://apis.io/apis/formify-eu/formify-eu-webhooks-api/)

## Tags

OAuth

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/formify-eu/formify-eu-oauth-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/formify-eu/.