Authentication

Formr supports two authentication methods: session tokens for dashboard operations and API keys for programmatic access.

API Keys

API keys are the primary method for authenticating API requests. They come in two types:

Publishable Keys

Format: pk_live_... or pk_test_...

Safe to expose in client-side code (browsers, mobile apps)
Use for form submissions from frontend applications
Include in the x-publishable-key header
Limited permissions - can only submit forms

POST /v1/forms/{formId}/submissions
x-publishable-key: pk_live_abc123...

Secret Keys

Format: sk_live_... or sk_test_...

Must be kept secret - never expose in client-side code
Use for server-side operations (creating forms, reading responses, etc.)
Include in the Authorization header as Bearer token
Full API access - can perform all operations

POST /forms
Authorization: Bearer sk_live_xyz789...

Session Tokens

Session tokens are obtained when users log in through the dashboard. They're used for authenticated dashboard operations and expire after a period of inactivity.

GET /forms
Authorization: Bearer <session-token>

Getting Your API Keys

Log in to your Formr dashboard at app.formr.xyz
Navigate to Settings → API Keys
Click "Create API Key"
Choose between publishable (pk_) or secret (sk_) key
Select the environment (production, development, staging)
Copy and securely store your key

Important: Secret keys are only shown once when created. Make sure to copy them immediately. If you lose a secret key, you'll need to create a new one.

Environments

API keys are scoped to workspace environments. Each environment (production, development, staging) has its own set of keys. This allows you to:

Test integrations in development without affecting production data
Use different keys for different environments
Rotate keys independently per environment

Error Responses

Authentication errors return a 401 status code:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}