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 (GET /public/form_data/{form_id}) and Submit a form response (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

1. Generate an API key

   API keys are created in the Paubox dashboard. Copy the key when it is displayed; store it somewhere safe.

2. 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.

3. Note the base URL

   All Forms API requests go to the same base URL:

   https://api.paubox.com/v1/forms
   

Pass credentials in requests

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

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

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

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.

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

# 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" ...