API keys

What API keys are for

API keys let scripts, AI tools, and API clients connect to your Loam data. Each key has its own permission rules, so you can allow only the workspace, datasets, tables, or views that client needs. Dataset permissions apply through any number of nested datasets, and you can explicitly deny a sensitive node beneath a broader allow.

Creating a key

1. Go to Settings > API keys (sign in to open this page).
2. Click Create key.
3. Give the key a descriptive name so you remember what it's for, such as "Monthly reporting script".
4. Under Permissions, choose the resources the key needs. Loam saves the selected resources by their stable IDs, so renaming a dataset or table does not move the key's access. Moving a node also keeps a direct rule attached to that node, while inherited access follows its new dataset ancestry.
5. For each allowed resource, choose an access level:
   • Viewer: the key can read data and metadata.
   • Editor: the key can mutate rows and create, change, or drop ordinary Tables and Views. It cannot manage grants, publication, connections, or dataset structure.
   • Admin: the key can manage the selected node and dataset structure within its allowed subtree, including table column schemas. Because an API key is a machine credential, even Admin cannot create, change, or delete grants.
6. Add an explicit Deny when a resource must stay unavailable. For example, allow the Reportingdataset and deny its Employee salaries table.
7. Click Create key. Your key appears once. Copy it now; you won't be able to view it again.

Using a key

First, exchange your API key for a short-lived access token by sending it to the workspace's regional data plane. The workspace public ID is part of the request path:

curl -X POST https://rw-us-east1.api.loamdata.com/v1/workspaces/rw-us-east1-ws-0195a3c47d3e7ab18c4f123456789abc/token/exchange \
  -H "Content-Type: application/json" \
  -d '{"token": "loam_your_api_key_here"}'

Use the returned jwt value as the Bearer token for Loam data API requests on the same regional host. Put the workspace public ID in each request path; no workspace-selection header is needed:

curl https://rw-us-east1.api.loamdata.com/v1/workspaces/rw-us-east1-ws-0195a3c47d3e7ab18c4f123456789abc/nodes \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

The access token expires after 15 minutes. Exchange the API key again when your client needs a new one. The access token contains the credential's identity, not its permissions. Loam checks the key's current permissions in the Engine for every request.

How permissions stay limited

A key can never have more access than the person who created it. Loam checks both the key's rules and that person's current access for every operation. If the person later loses access or receives an explicit deny, the key is limited immediately, including when its current access token has not expired. The permissions shown in settings come from the Engine; they are not stored in the API key or access token.

Managing keys

On the Settings > API keys (sign in to open this page) page, you can see all your active keys and when they were created.

• Revoke a key from its row. That key's Engine identity is deactivated, so future exchanges and requests using already-issued access tokens fail.
• Rotate a key by revoking the old one and creating a new one. You can update an existing key's permission rules, but its secret is never shown or replaced.

Security tips

• One key per client. Create separate keys for each script or client so you can revoke one without affecting the others.
• Use the lowest access level possible. Prefer Viewer for read-only clients and Editor when a client only needs to change rows or ordinary tables and views. Admin gives broad dataset, schema, and deletion authority, so use it only for trusted automation. Machine credentials cannot delegate grants, even with Admin.
• Keep keys secret. Treat API keys like passwords. If a key is exposed, revoke it immediately and create a new one. Revocation deactivates the key's Engine identity, so already-issued access JWTs fail on their next authorization.