> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paubox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate to the Paubox Forms API with a scoped API key.

The Paubox Forms API has two tiers of endpoints:

* **Public respondent endpoints** require no authentication. These are the endpoints called from end user devices when a respondent loads or submits a form: [Get form metadata](/forms/get-form) (`GET /public/form_data/{form_id}`) and [Submit a form response](/forms/submit-form) (`POST /api/forms/{form_id}/submissions`). The form's UUID acts as access control.
* **Form management endpoints** require a Paubox API key with the `forms` scope. This covers everything else: listing, creating, updating, copying, archiving, and unarchiving forms, retrieving form statistics, and reading or exporting submissions.

## Find your credentials

<Steps>
  <Step title="Generate an API key">
    API keys are created in the Paubox dashboard. Copy the key when it is displayed; store it somewhere safe.
  </Step>

  <Step title="Confirm the key has the forms scope">
    Paubox API keys are scoped per product. The key must include the `forms` scope to call the Forms API. A key scoped only to other products (for example, the Email API) is rejected with `401 Unauthorized`.
  </Step>

  <Step title="Note the base URL">
    All Forms API requests go to the same base URL:

    ```
    https://api.paubox.com/v1/forms
    ```
  </Step>
</Steps>

## Pass credentials in requests

Include the `Authorization` header with every form-management API call:

```bash theme={null}
curl --request GET \
  --url 'https://api.paubox.com/v1/forms/api/forms?customer_id=YOUR_CUSTOMER_ID' \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

The Forms API accepts Bearer tokens only:

```
Authorization: Bearer YOUR_API_KEY
```

<Note>
  The Forms API does not accept the `Token token=` header format used by the Paubox Marketing API. Always use `Bearer`.
</Note>

## Authentication errors

| Status             | Meaning                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | The `Authorization` header is missing, the API key is invalid, or the key does not include the `forms` scope. |
| `403 Forbidden`    | The API key is valid, but the requested resource belongs to a different customer.                             |

## Key handling

* Generate a new key before revoking an old one to avoid downtime.
* Revoke keys immediately if they are exposed or a team member with access leaves.

<Warning>
  Never commit API keys to source control. Use environment variables or a secrets manager to inject credentials at runtime.

  ```bash theme={null}
  # Good
  export PAUBOX_API_KEY=your_api_key
  curl -H "Authorization: Bearer $PAUBOX_API_KEY" ...

  # Bad: do not do this
  curl -H "Authorization: Bearer a5e1ec4aefaa5fef1a9a2a46459eeae3503034a9" ...
  ```
</Warning>