Documentation
API Keys

API Keys

An API key lets your own code use the Project Context API of one project: its live readings, variables, events and board status, and, if you allow it, setting its variables and running its modules.

A project has no key until you make one. Any project can have its own keys.

⚠️

Treat a key like a password. Keep it in a .env file on a machine or server you control, and never commit it. Never paste it into a chat, an AI prompt, a web page or browser code. Anyone holding it can read the project, and with Can control, change it.

One key, one project

A key belongs to exactly one project. It cannot open any other project, even another one of yours, and a connection made with it sees only that project's boards (the ones assigned under ⋯ → Manage devices). Make one key per project and per app, so you can revoke one without touching the others.

Creating a key

  1. Open the project in the Palpable app.
  2. Open the project menu (⋯) → Access.
  3. Under Apps, choose Add an app.
  4. Name it after what will use it (e.g. "Kitchen dashboard"). You can also give its dashboard URL, which adds it to the project as a view.
  5. Choose Can view (read only) or Can control (also set variables and run module commands).
  6. Copy the key into your .env file. It is shown once and cannot be shown again.
# .env — never commit this file
PALPABLE_PROJECT_ID=550e8400-e29b-41d4-a716-446655440000
PALPABLE_API_KEY=pk_…

A key is pk_ followed by 64 lowercase hex characters. The app shows its first 10 characters so you can tell keys apart. Palpable stores only a SHA-256 hash of it.

Who can make a key. The project's owner, or a member of the team the project belongs to. Anyone else is refused (HTTP 403), and a key whose maker no longer has access to the project is refused when it next connects.

Seeing and revoking keys

⋯ → Access lists the project's apps under Apps, each with its key's first characters and whether it is connected now or when it was last seen. Remove an app to revoke its key.

Revoking takes effect at once: every open connection using the key is closed (WebSocket close code 4401, reason API key revoked) within a second or two, and the key is refused from then on.

Account keys (legacy)

Keys under Settings → Developer → API keys are account keys: one key for every project you own. They still connect to the Project Context API, but read-only, and each connection is sent a LEGACY_ACCOUNT_KEY notice. Use project keys instead: create a key in each project that uses an account key, switch your app over, then revoke the account key in Settings.

Using a key

const res = await fetch(`https://palpable.technology/api/projects/${process.env.PALPABLE_PROJECT_ID}/connect`, {
  headers: { Authorization: `Bearer ${process.env.PALPABLE_API_KEY}` },
})
const { wsUrl } = await res.json()
// then open `${wsUrl}?token=${process.env.PALPABLE_API_KEY}` — see the Project Context API

The full protocol (channels, messages, errors and close codes) is in Project Context API.