Build with the API

API keys and scopes

Create a key, choose what it may do, and why it is never more powerful than its owner.

An API key lets a program act as you. It is the right tool for scripts, servers, integrations and AI agents. This guide shows how to make one, what it can be allowed to do, and how it stays safe.

In the dashboard

Open Developers → API keys and choose Create a key: name it, tick what it may do, and copy the key from the next screen. It is shown once; Gridline keeps only a fingerprint. The list shows each key's name, what it may do, who made it (admins see everyone's), when it was last used, and a Revoke button.

Create a key

POST/api-keysNeeds a session. A key cannot make keys.

namestringrequired: What it is for, so you can tell your keys apart and revoke the right one, up to 80 characters.
scopesstring[]required: What it may do. At least one, no repeats. See the table below.

curl https://gridline-data-analysis-app.duckdns.org/api/api-keys \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Nightly import", "scopes": ["files:read", "files:write"] }'

Use it like any token:

curl

curl https://gridline-data-analysis-app.duckdns.org/api/files -H "Authorization: Bearer gl_live_ab12cd34_…"

Scopes

A scope is a permission a key carries. A key can do something only if it holds the scope and its owner may do it.

Scope	Who may give it	What it opens
`files:read`	Anyone	List and read files, versions, comparisons, reports and previews, download links, comments, the plan and its quota, and the quality rules.
`files:write`	Anyone	Upload files and new versions, change who can see a file, delete a file, rebuild a report.
`notifications:read`	Anyone	Read your own notifications and mark them read.
`mcp`	Anyone	Use the AI-agent endpoint. Which tools the agent gets depends on the other scopes.
`billing:read`	Admins	The running bill and invoices.
`rules:write`	Admins	Create, edit and delete quality rules.
`audit:read`	Admins	Read the audit log.

An employee who tries to give a key an admin-only scope is refused with 403. You cannot hand out what you do not have.

What a key can never do

Keys are closed by default. Any endpoint that does not explicitly say "keys welcome" refuses them. That means a leaked key can never:

sign in, change a password or reach your account settings;
invite or remove people, or change a plan;
make, list or revoke API keys (so it cannot create a copy of itself);
manage webhooks, change company details, or read analytics or GraphQL;
write comments.

A key is a name for its owner

A key is not a separate user. It acts as the person who made it, as they are right now. Their files are its files; their access is its access.

Demote the person and the key loses any admin scopes on its next request.
Disable the person and every key they made stops working at once.
The audit log records which key did what.

Manage keys

GET /api-keys: an admin sees the company's keys; an employee sees only their own. Newest first. The list shows the key's prefix and lastUsedAt, never the key itself.
DELETE /api-keys/{id}: revoke. An admin can revoke any key; an employee only their own (someone else's is a 404). Revoking twice is fine.