Create an API key with the same Account / Project role model used for members — pick an Account Role, pick projects and a Project Role (skipped when Owner is chosen), set expiration, and copy the key once
Updated May 8, 2026API keys are how scripts, CI pipelines, Terraform, and any non-interactive automation authenticates against Raff. They use the same role-based permission model as members — you give a key an Account Role and (unless you picked Owner) a Project Role applied to one or more projects. The same account.* and project.* permission catalog applies; the key carries a frozen snapshot of that role’s permissions when it’s used.This page walks the dashboard create flow.
Type a descriptive label. The name shows up in the API Keys list, in audit-log entries when the key is used, and in invoice line items if the key creates billable resources.Pick a name that tells you immediately what owns this key — Backups Lambda, Terraform Prod, On-call dashboard. Avoid vague names like key1.
This determines the key’s account.* permissions. The dropdown lists every account-scope role in your account (System + Custom).
The four System options at a glance (see Permissions matrix for full detail):
Option
When to pick
Owner(21 permissions — full access)
The key needs to do everything the Owner can — including managing members, billing, audit, every project. Step 2 is skipped because Owner already covers all projects
Admin(15)
Account management except destructive actions and billing — useful for an ops-automation key that creates projects, invites members, generates other keys
Billing(2)
A key for an accounting integration that pulls invoices and updates payment methods — nothing else
Member(3)
The narrowest account role — view projects, members, settings. Useful as a base for a key that lives mostly in projects
The Manage Roles link in the top-right of this section opens the Roles tab in a new context so you can review or create Custom roles before finalizing the key.
The screenshot above (Owner selected) shows what’s special about Owner: the dialog hides Step 2 entirely because Owner means “everything in every project, current and future.” A blue banner makes this explicit:
Full access — this key will have owner-level permissions across all projects. No project selection needed.
This is the right choice for a small team’s single power key, or a setup-time bootstrap key. It’s also the riskiest — if leaked, it can do anything. Prefer narrower roles for keys that only need a slice.
Pick anything other than Owner in Step 1 and a new section appears: Step 2 - Resource Access.
Step 2 has two fields:
Field
What goes here
Projects
Tick every project the key should be able to reach. Tick zero, and the key has only its account-level permissions (no project-resource visibility). Tick one or many — the same Project Role applies to all of them
Project Role
Pick a Project Role (System: Project Admin, Operator, Project Member, Viewer; or any Project-scoped Custom role). The dropdown shows the permission count next to each name
The helper text under Project Role spells out the constraint that’s worth highlighting: “Determines what resources this key can manage in the selected projects. The same role is applied to all selected projects.” You cannot give the key different roles on different projects in one create. If you need that, create one key per role — narrower scope is better security anyway.A typical filled-in Step 2:
The example above creates a key with:
Account access:Admin (15 permissions — full account management except destructive operations and billing)
Project access:Operator on both the Default project and customer1 (29 permissions per project — manage VMs/VPCs/IPs/etc. but no delete)
That’s a typical “ops automation” scoping — broad enough to do real work, narrow enough that a leak isn’t catastrophic.
Most production integrations should use at least one of the bounded options so the key actively expires if you forget about it. Set a calendar reminder a week before expiry to rotate (see Rotate an API key).The Expiration field is configured at create time; it cannot be extended later. To extend a key’s life, rotate to a new key with a fresh expiry.
The bottom of the dialog has a Permissions Preview — a collapsed summary of what the key will be able to do based on Step 1 and Step 2:
Account Permissions (<role>) — N permissions
Project Permissions (<role>) — N permissions(when Step 2 is filled)
Click the chevron next to each row to expand and see the exact permission list — the same view shown in the role-detail dialog, just inline. Use this to verify the key has what it needs and nothing more before you click Create.If you realize the preview is missing a permission — for example, the key needs vm.console and the Project Role you picked doesn’t include it — don’t toggle the permission directly here. That’s not how the dialog works. The fix is to:
Cancel the create
Either pick a different Project Role that includes the missing permission, or
Open Roles → + Create Role to build a Custom role with exactly the permissions you need
Come back to Create API Key and pick the Custom role
This is the centralized role system working as designed: every grant — to a member or to a key — references a role definition. To change what a key can do, you change the role (and every key/member using it changes with it), or you create a new role and re-issue.
The key is generated and the dashboard shows it in a one-time API Key Created dialog.
This is the only time the full key will be shown. Click the copy button and paste it into your secret store before clicking Done. Once the dialog closes, only the key’s prefix (raff_17d70fcf…) remains visible — the rest can never be retrieved. If you lose it, the only fix is to rotate to a new key.
Every Raff API key starts with the raff_ prefix followed by a long random suffix — easy to grep for in code reviews and to detect accidental commits to source control. Pipe the key straight into your secret manager:
1Password / Bitwarden — paste into a secure note tagged for this integration
The list is the at-a-glance summary of everything in your account. Each column:
Column
What it shows
Name
The label you typed at create time
Key Prefix
The first ~12 characters of the key — enough to identify it in audit logs without exposing the secret. The full key is gone forever after the create dialog closes
Account Role
The Account Role you picked in Step 1 (e.g. Admin, Owner, or your Custom role name)
Project Access
A badge per project the key has access to, with the Project Role shown in parentheses — e.g. customer1 (Project Admin), Default (Project Admin). Owner-keys show All projects instead. Empty when the key has no project access
Expires
The chosen expiration — Never for never-expires, or a date for any time-bounded option. Past-due keys show Expired
Last Used
When the key last authenticated a request. Never for unused keys; otherwise a relative timestamp like 2 hours ago
Created
When the key was generated
Each row also has two actions on the right:
Action
Icon
What it does
Regenerate
🔄 cycle
Rotates the key — issues a new key value (with the same name, scope, and expiration) and immediately invalidates the old key. Use when the key may be compromised, when you’re rotating per policy, or when you want to extend a key’s life past its current expiration. See Rotate an API key
Delete
🗑️ red trash
Permanently revokes the key. The key value is deleted; any in-flight requests using it fail with a 401. Cannot be undone — recreate from scratch if you delete by mistake
The list refreshes when you create, regenerate, or delete a key. Last Used updates a few seconds after a successful API call from the key.
For project-scoped requests (every endpoint that lists or creates a resource in a project), include the X-Project-ID header set to one of the projects the key has access to. The combination of X-API-Key + X-Project-ID lets the API resolve which permission set to apply.For account-only operations (members, billing, etc.), X-Project-ID is omitted — the key’s Account Role permissions apply directly.
The full request reference is on Authentication. It covers: the exact header set, language SDK setup (Python, Node, Go), example requests for the most common endpoints, and the 401 / 403 responses you’ll see when the key is missing, invalid, expired, or scoped wrong. Bookmark that page when you’re integrating Raff into a new application.
Edit a key’s permissions after create — to change a key’s access, rotate it. The key’s role at create-time is frozen on the key record
Assign different Project Roles to different projects in the same key — one Project Role applies to every selected project. Create separate keys when projects need different scopes
Recover the full key after the create dialog closes — only the prefix is preserved. If you lose the key, rotate to a new one
Extend the expiration — if a key is about to expire, rotate to a new key with a fresh expiry
