Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.propal.io/llms.txt

Use this file to discover all available pages before exploring further.

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:
  1. Navigate to Settings > API Keys
  2. Click Create API Key
  3. Enter a name (e.g., “Zapier Integration”, “Internal Dashboard”)
  4. Select the scopes (permissions) the key should have
  5. 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

ResourceReadWriteDelete
Proposalsproposals:readproposals:writeproposals:delete
Leadsleads:readleads:writeleads:delete
Catalogproducts:readproducts:writeproducts:delete
Templatestemplates:readtemplates:writetemplates:delete
Themesthemes:readthemes:writethemes:delete
Mediamedia:readmedia:writemedia:delete
Metricsmetrics:read——
Organizationorganization:read——

​
Scope combinations by use case

["leads:read", "proposals:read", "metrics:read"]
Ideal for syncing data from Propal to your CRM without modifying anything.
[
  "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.
["metrics:read", "proposals:read", "organization:read"]
Build custom dashboards with your proposal metrics and pipeline data.
All scopes selected. Use this only for trusted internal tools.

​
Security best practices

1

Use minimal scopes

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

Rotate keys periodically

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

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

Use environment variables

Store keys in environment variables or a secrets manager — never hardcode them.
export PROPAL_API_KEY="pp_live_your_key_here"
5

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"
  }
}