Formify Auth API

openapi: 3.2.0
info:
  title: Formify Auth API
  description: '## Overview


    The Formify API lets you send documents for electronic signature, prepare drafts, track signing status, and retrieve signed documents. It is designed for integrating signing workflows into your application.


    ### Getting Access


    OAuth 2.0 is the recommended way to access the API. Before you can use the API, you need an OAuth 2.0 client. Formify creates this for you based on information about your company, contacts, and redirect URIs. See the **Getting Access** guide for setup instructions.


    Once your OAuth client has been created, you can use the OAuth 2.0 Authorization Code flow to obtain access tokens for API requests.


    For MCP clients and third-party platforms that cannot complete OAuth/PKCE and only accept a pasted token, a Formify API key can be exchanged for a short-lived access token with `POST /auth/token`. This is a compatibility option; use OAuth where the client supports it.


    ### Authentication


    Protected API requests use a Bearer access token. The recommended flow is OAuth 2.0: your application redirects the user to Formify for authorization, receives an authorization code, and exchanges it for an access token. See the OAuth 2.0 section for the complete flow.


    ### Environments


    **API base URL**: `https://docs-api.formify.eu/v1`

    All document operations, file uploads, and token exchange endpoints (OAuth and API key fallback) happen here.


    **Authorization Server**: `https://app.formify.eu`

    This is where users authorize your application and approve access (the OAuth consent).


    ### Rate Limiting


    The API uses token-based rate limiting to ensure fair usage:


    - **Headers**: Every response includes rate limit headers:

    - `X-RateLimit-Limit`: Maximum requests allowed

    - `X-RateLimit-Remaining`: Requests remaining in current window

    - `X-RateLimit-Reset`: The number of seconds until the rate limit resets


    - **Not every request costs the same.** Endpoints that build or copy a document consume several tokens

    rather than one, because they render a PDF and make multiple calls to the document service. Creating,

    editing or duplicating a document or a public link is the most expensive; creating or editing a template

    costs less; deleting and duplicating a draft less again. Plain reads cost one.


    If you exceed the limit, the API returns `429 Too Many Requests`. Wait until the reset time before making additional requests.


    ---


    ## Quick Start: Send a PDF for Signing


    Once you have a valid `access_token`, you can send your first document for signing in three steps:


    ### 1. Upload a PDF

    Upload a PDF file using the Upload File endpoint:


    ```bash

    POST /files

    Content-Type: multipart/form-data

    ```


    You will receive a `fileId` in the response.


    ### 2. Create a Signature Request

    Send the document for signing using the Create Document endpoint:


    ```bash

    POST /docs

    {

    "fileId": "your-file-id",

    "signeeDetails": [

    {

    "fullName": "John Doe",

    "emailAddress": "john@example.com",

    "signaturePlacement": "new_page"

    }

    ]

    }

    ```


    The response returns a documentId. The signee then receives an email with a link to sign the document.


    ### 3. Get Notified and Download

    Register a webhook to receive a notification when the document is signed:


    ```bash

    POST /webhooks

    {

    "webhookUrl": "https://your-app.com/webhook",

    "eventTypes": ["document.completed"]

    }

    ```


    Then download the signed PDF using Get Signed Document File:


    ```bash

    GET /docs/{documentId}/signed-file

    ```


    For more detailed walkthroughs, see the **Integration Flows** guide.


    ---


    ### Help


    - **Getting Access** - How to set up OAuth 2.0 credentials

    - **Integration Flows** - Step-by-step guides for common integration scenarios

    - **PDF Form Attributes** - How to add `tink-*` attributes to PDF form field names

    - **MCP Server** - Connect AI assistants with OAuth or an API key fallback for token-only clients

    - **Production Checklist** - Essential steps before going live


    ### Links


    - Formify API Changelog - Track API updates and changes

    - Formify App - Register OAuth applications and manage settings


    ---'
  contact:
    email: api@formify.eu
  version: 1.5.2
  termsOfService: https://formify.eu/privacy/terms
servers:
- url: https://docs-api.formify.eu/v1
  description: Main API server for all document related endpoints and token exchange.
security:
- OAuth2: []
tags:
- name: Auth
  description: '## API Key Token Exchange


    OAuth 2.0 with PKCE is the recommended authentication method for Formify API integrations because users authorize access in Formify and clients do not need to store long-lived API keys.


    Some MCP clients and third-party platforms cannot complete an OAuth/PKCE flow and only allow a user to paste a token. For those cases, a Formify API key can be exchanged for a short-lived Bearer `access_token` using `POST /auth/token`.


    Use the returned `access_token` with `Authorization: Bearer {access_token}` when calling protected API endpoints. Do not call protected endpoints directly with the API key.'
paths:
  /auth/token:
    post:
      tags:
      - Auth
      summary: Exchange Formify API key for short-lived access token
      description: 'Exchange a Formify API key, for example `sk_live_YOUR_API_KEY`, for a short-lived Bearer `access_token`. Test keys use the same format with the `sk_test_` prefix.


        OAuth 2.0 with PKCE remains the recommended authentication method for integrations that support it. This endpoint exists for MCP clients and third-party platforms that cannot complete OAuth/PKCE and only allow a user to paste a token.


        Send the API key in the `Authorization` header using the `ApiKey` scheme:


        ```http

        Authorization: ApiKey sk_live_YOUR_API_KEY

        ```


        The response contains an `access_token` that is used exactly like an OAuth access token:


        ```http

        Authorization: Bearer {access_token}

        ```


        Do not call protected API endpoints directly with the API key.'
      operationId: exchangeApiKeyForAccessToken
      x-codeSamples:
      - lang: curl
        source: "curl -X POST \"https://docs-api.formify.eu/v1/auth/token?scope=read%20write\" \\\n  -H \"Accept: application/json\" \\\n  -H \"Authorization: ApiKey sk_live_YOUR_API_KEY\""
      - lang: JavaScript
        source: "const response = await fetch(\"https://docs-api.formify.eu/v1/auth/token?scope=read%20write\", {\n  method: \"POST\",\n  headers: {\n    \"Accept\": \"application/json\",\n    \"Authorization\": \"ApiKey sk_live_YOUR_API_KEY\"\n  }\n});\n\nconst data = await response.json();\nconsole.log(data.access_token);"
      - lang: Python
        source: "import requests\n\nresponse = requests.post(\n    \"https://docs-api.formify.eu/v1/auth/token\",\n    params={\"scope\": \"read write\"},\n    headers={\n        \"Accept\": \"application/json\",\n        \"Authorization\": \"ApiKey sk_live_YOUR_API_KEY\",\n    },\n)\n\nprint(response.json()[\"access_token\"])"
      parameters:
      - name: scope
        in: query
        required: false
        schema:
          type: string
          enum:
          - read
          - write
          - read write
          default: read write
        description: Requested access scope. Use `read`, `write`, or `read write`. Defaults to `read write` if omitted.
      responses:
        '200':
          description: Access token generated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyTokenResponse'
              example:
                access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                token_type: Bearer
                expires_in: 3600
                scope: read write
        '400':
          description: Missing or invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or disabled API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
      security:
      - ApiKeyAuth: []
components:
  schemas:
    ErrorResponse401:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Unauthorized
        code:
          type: integer
          example: 401
        language:
          type: string
          example: en
    ApiKeyTokenResponse:
      type: object
      required:
      - access_token
      - expires_in
      - token_type
      - scope
      description: 'Token response returned after exchanging a Formify API key at `/auth/token`.


        This response is intentionally aligned with OAuth token responses so clients can use the returned `access_token` in the same way: send it as `Authorization: Bearer {access_token}` to protected API endpoints.


        API key exchange does not return a `refresh_token`. When the access token expires, exchange the API key again.'
      properties:
        access_token:
          type: string
          description: The short-lived JWT access token used for authenticating API requests.
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        expires_in:
          type: integer
          description: The lifetime of the access token in seconds.
          example: 3600
        token_type:
          type: string
          description: The type of token issued. Always `Bearer`.
          example: Bearer
        scope:
          type: string
          description: Space-separated list of permissions granted to this token (`read`, `write`, or `read write`).
          example: read write
    ErrorResponse500:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Internal Server Error
        code:
          type: integer
          example: 500
        language:
          type: string
          example: en
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Invalid request parameters
        code:
          type: integer
          example: 400
        language:
          type: string
          example: en
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'HTTP Basic Authentication for traditional OAuth clients. Send `Authorization: Basic base64(client_id:client_secret)`.'
    ApiKeyAuth:
      type: http
      scheme: ApiKey
      description: 'Formify API key authentication for `POST /auth/token` only. Send the API key using the HTTP authorization scheme format `Authorization: ApiKey sk_live_YOUR_API_KEY` to exchange it for a short-lived Bearer access token. Test keys use the same format with the `sk_test_` prefix.'
    OAuth2:
      type: oauth2
      description: OAuth2 Authentication. Allows third-party systems to access the API on behalf of the user and their account after authorization.
      flows:
        authorizationCode:
          authorizationUrl: https://docs-api.formify.eu/v1/oauth/authorize
          tokenUrl: https://docs-api.formify.eu/v1/oauth/token
          scopes:
            read: Allows reading documents and their metadata
            write: Allows modifying documents and sending signature requests
externalDocs:
  description: Formify website
  url: https://formify.eu
x-tagGroups:
- name: Authentication
  tags:
  - oauth
  - auth
- name: Documents
  tags:
  - files
  - docs
  - drafts
  - templates
  - links
- name: Account & User
  tags:
  - user
  - account
- name: Webhooks
  tags:
  - webhooks