Authentication - Getting Started - PlanDocket Documentation

API Keys

Authentication is done via API keys. To create a key:

Log in to the admin area
Navigate to Settings > API
Click "Create new API key"
Select the required scopes

Using API Keys

Pass your API key in one of the following headers. A query parameter is only accepted if the platform operator has enabled it:

Bearer Token (recommended)

curl -X GET "https://your-tenant.plandocket.com/api/v1/events" \
  -H "Authorization: Bearer YOUR_API_KEY"

X-API-Key Header

curl -X GET "https://your-tenant.plandocket.com/api/v1/events" \
  -H "X-API-Key: YOUR_API_KEY"

Query Parameter Disabled by default

curl -X GET "https://your-tenant.plandocket.com/api/v1/events?api_key=YOUR_API_KEY"

Disabled by default – this method only works if the platform operator has enabled it; otherwise the request is rejected with 401. It is not recommended, as the key may appear in server logs and browser history. Use the Authorization or X-API-Key header instead.

Scopes

API keys can be restricted to specific scopes:

Scope	Access
`events`	Read and write events
`contacts`	Read and write contacts
`participants`	Read and write participants
`applications`	Read and manage applications
`categories`	Read and write categories
`checkins`	Read and create check-ins
`invoices`	Read and write invoices
`payments`	Read and record payments
`booths`	Read and write booths and reservations
`plans`	Read floor plans
`schedules`	Read schedules
`services`	Read services
`service_orders`	Read service orders
`submissions`	Read and manage submissions
`documents`	Read and generate documents
`tasks`	Read and write tasks
`custom_fields`	Read and write custom fields
`lists`	Read and edit the list entries of participants
`newsletter`	Manage newsletter subscribers
`reports`	Retrieve reports
`audit`	Read audit log
`webhooks`	Manage webhooks
`calendar-feed`	Read calendar feed

Access levels

Every scope can be granted with an access level. Grant read access to integrations that only export data (BI tools, dashboards).

Notation	Allowed requests
`contacts:read`	Read only: GET requests
`contacts:write`	Read and write: GET, POST, PUT, PATCH and DELETE
`contacts`	Read and write (keys created before access levels were introduced)

Unrestricted access must be chosen explicitly with the "Full access" option when creating the key; such a key (stored without any scope) has full read and write access to every resource. Restricted keys need at least one scope. Requests that need write access with a read-only scope are rejected with 403.

Security

Important Security Notes

Never use API keys in frontend code
Store keys in environment variables
Rotate keys regularly
Grant only the minimum required scopes