Settings → API keys

Audience

Workspace administrators and members issuing keys for their own automations.

API keys let your own scripts call PLANA's API as if they were you, scoped to one workspace. Use them for nightly syncs, custom dashboards, webhooks into other systems — anything that talks to PLANA without a human at the keyboard.

What you see

A table of your workspace's keys:

Column	Detail
Name	The label you gave the key
Prefix	pa_live_AB7K2… — the first 12 chars (the full key was shown only once at creation)
Scope	What the key can do
Created by	The member who issued it
Created at	Date
Last used	Last successful API call (or "Never")
Actions	Copy prefix · Revoke

You cannot recover the full plaintext after creation. If you lose it, revoke and issue a new one.

Creating a key

Click + Create key. Fill in:

Field	What
Name	e.g. "Nightly stock sync to ERP-X" — descriptive, helps audit later
Scope	One or more of: dashboard:read, agents:invoke, banking:read, webhooks:write, *
Expiry (optional)	Date after which the key stops working; default no expiry

Click Create key → the full token is shown in a copy-to-clipboard field once. Save it immediately to your secrets manager (Vault, Doppler, 1Password CLI, AWS Secrets Manager).

Format: pa_live_AB7K2XYZ1234... (32 random base32 bytes after the prefix).

Scopes

Scope	Grants
dashboard:read	KPIs, cashflow series, alerts
agents:invoke	POST to /api/agents/:id/chat
banking:read	PSD2 accounts and transactions
webhooks:write	Register / receive webhook events
*	Everything (discouraged; use only when needed)

A key with dashboard:read only cannot invoke an agent. Trying returns 403 with a clear error.

What keys cannot do

• Modify the workspace's own configuration
• Manage the team
• Write to PLANA Business Cloud records directly (no Odoo XML-RPC bridge)
• Access another workspace's data

Interactive sign-in (the BOS UI) handles those.

Revoking a key

Click Revoke on the row → confirm. The key stops working within seconds:

• In-flight requests using the key complete (no abrupt cancel)
• New requests return 401
• The key remains in the audit log (for compliance) but cannot be reused

Using a key in code

curl

curl -s "https://my.planapulse.ai/api/portal/odoo/acme/kpis" \
  -H "Authorization: Bearer pa_live_AB7K2..."

Python

import os, requests
resp = requests.get(
    "https://my.planapulse.ai/api/portal/odoo/acme/kpis",
    headers={"Authorization": f"Bearer {os.environ['PLANA_KEY']}"},
)
resp.raise_for_status()
print(resp.json())

Node

import 'dotenv/config'
const r = await fetch('https://my.planapulse.ai/api/portal/odoo/acme/kpis', {
  headers: { Authorization: `Bearer ${process.env.PLANA_KEY}` },
})
console.log(await r.json())

Note: the workspace slug appears in the URL (/odoo/acme/); the key must belong to that workspace.

Best practices

Practice	Why
Store the key in a secrets manager, never in source	Source leaks happen
Issue one key per automation, scoped tight	Compromise of one doesn't compromise all
Set an expiry on short-lived integrations	Defence in depth
Rotate annually	Limits the blast radius of an unknown leak
Watch BOS → Execution log for unexpected calls	Detect compromise early

Audit

Every call authenticated by a workspace key appears in the Execution log with the key prefix (not the full token). If you spot a call you didn't authorize, revoke the key immediately and investigate.

Where to read more

• Workspace — workspace-wide settings
• Execution log — the audit feed
• Workflows → Rotate an API key — the procedure
• Platform → Identity → API keys — technical details