An API key authenticates you to GraphPilot, without a browser. It is what the CLI uses in CI, and what a script calling the GraphPilot API presents, for example to purge. You create and manage keys in the portal, under your organization’s Settings → API keys. Who can do what with keys depends on the role:
| Role | Organization keys | Own personal keys | Other members’ personal keys |
|---|---|---|---|
| Admin | Create and revoke | Create and revoke | See and revoke |
| Developer, Member | Create and revoke | Create and revoke | No |
| Viewer | No | Create and revoke | No |
A key can only be given permissions its creator holds, so a Viewer’s personal key can only read.
GraphPilot issues keys at two levels. They differ in who owns the key, not in what it can do: either kind acts with the permissions chosen for the key, never with the role of the member who created it.
Organization keys
Recommended for most integrations. The key belongs to the organization and is shared by its members for programmatic access. It is not tied to any single person, so it keeps working as people join or leave the team. That makes it the right choice for services, CI/CD, and server-side integrations.
Personal keys
Linked to an organization, but owned by your user account. Use these for your own ad-hoc access. Because the key is tied to your account, revoke it yourself when you leave that organization; it stops working when your account is deleted.
| Organization key | Personal key | |
|---|---|---|
| Owned by | The organization | You (linked to an organization) |
| Acts with | The key’s own permissions | The key’s own permissions, not your role |
| Shown in the portal as | The key’s name and redacted value | The key’s name and redacted value |
| Shared by the team | Yes | No |
| Survives a member leaving | Yes | No: an Admin revokes it when the member leaves |
| Best for | Services, CI/CD, integrations | Your own ad-hoc access |
Rule of thumb: reach for an organization key by default. A personal key does not make a request act as you: where the portal names who changed something, it names the key, not the person who owns it.
A key can do exactly what its permissions allow, and nothing else; you choose them when you create
the key. You can choose only permissions your own role holds by name, so a role meant to create a
read-only key lists service:view next to service:edit. Which permissions a key can carry, and
which each job needs, is on permissions.
Some permissions are never available to a key, whatever was selected for it: organization
settings, billing changes, the signing key and deleting a service among them. They are dropped
from the key when it is used, and the key keeps the rest. A key left with none of the
permissions a key may hold is refused with 401, “API key not accepted: every permission it
carries is one an API key may not hold.” See when a credential is refused.
A client that presents many different unknown keys in a short time is answered 429; see API
key validation.
Open the portal and go to your organization’s Settings → API keys.
Choose the section for the kind of key you need (Organization keys or Personal keys) and create a new key. Name it after what uses it, and select its permissions.
Copy the key immediately. The full secret is shown only once, right after creation. Store it in a secret manager; you cannot retrieve it again later.
Treat the key like a password: never commit it to source control, and inject it through your platform’s secret store rather than hard-coding it. To use it with the CLI, see signing in to the CLI.
Revoke a key from the same Settings → API keys screen. Once revoked, the key can no longer be used to authenticate. Note the delay below before assuming it is fully disabled.
To keep request latency low, GraphPilot caches the result of API key authentication for up to 60 seconds. Because of this cache, revoking a key is eventually consistent rather than instant:
gpilot