Authentication

Every request to the Propal API must include an API key in the Authorization header.

Authorization: Bearer pp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are scoped to a single organization. All data accessed through a key belongs to that organization — there’s no cross-organization access.

Creating API keys

You can create API keys from your Propal dashboard:

Navigate to Settings > API Keys
Click Create API Key
Enter a name (e.g., “Zapier Integration”, “Internal Dashboard”)
Select the scopes (permissions) the key should have
Click Create Key

The full API key is displayed only once at creation time. Copy it immediately and store it securely.

Key format

API keys follow the format:

pp_live_<random_base64url_string>

pp_live_ — fixed prefix, identifies this as a Propal API key
The rest is a cryptographically random string

Keys are stored as SHA-256 hashes in our database — we never store the raw key. If you lose it, you’ll need to create a new one.

Scopes

Each API key has a set of scopes that define what it can access. Scopes follow the format {resource}:{action}.

Available scopes

Resource	Read	Write	Delete
Proposals	`proposals:read`	`proposals:write`	`proposals:delete`
Leads	`leads:read`	`leads:write`	`leads:delete`
Catalog	`products:read`	`products:write`	`products:delete`
Templates	`templates:read`	`templates:write`	`templates:delete`
Themes	`themes:read`	`themes:write`	`themes:delete`
Media	`media:read`	`media:write`	`media:delete`
Metrics	`metrics:read`	—	—
Organization	`organization:read`	—	—

Scope combinations by use case

CRM Integration (read-only)

["leads:read", "proposals:read", "metrics:read"]

Ideal for syncing data from Propal to your CRM without modifying anything.

Full Automation

[
  "proposals:read", "proposals:write",
  "leads:read", "leads:write",
  "products:read",
  "templates:read",
  "themes:read"
]

Create proposals automatically from your pipeline. Read-only on catalog, templates, and themes.

Analytics Dashboard

["metrics:read", "proposals:read", "organization:read"]

Build custom dashboards with your proposal metrics and pipeline data.

Full Access

All scopes selected. Use this only for trusted internal tools.

Security best practices

Use minimal scopes

Only grant the scopes your integration actually needs. A read-only dashboard doesn’t need write or delete permissions.

Rotate keys periodically

Revoke and recreate API keys on a regular basis (e.g., every 90 days).

Never expose keys in client-side code

API keys should only be used in server-side code, backend services, or CI/CD pipelines. Never include them in JavaScript bundles, mobile apps, or public repositories.

Use environment variables

Store keys in environment variables or a secrets manager — never hardcode them.

export PROPAL_API_KEY="pp_live_your_key_here"

Monitor usage

Check the “Last used” column in Settings > API Keys to detect unexpected activity.

Error responses

If authentication fails, you’ll receive a 401 Unauthorized response:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key."
  }
}

If your key doesn’t have the required scope for an endpoint, you’ll get a 403 Forbidden:

{
  "error": {
    "code": "forbidden",
    "message": "API key missing required scope: proposals:write"
  }
}

Overview

Guides

Endpoints

Authentication

Creating API keys

Key format

Scopes

Available scopes

Scope combinations by use case

Security best practices

Error responses

​Creating API keys

​Key format

​Scopes

​Available scopes

​Scope combinations by use case

​Security best practices

​Error responses

Creating API keys

Key format

Scopes

Available scopes

Scope combinations by use case

Security best practices

Error responses