Formify OAuth API
## 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