[simlarsen]

What

API keys can now be given custom roles, the way teams are. The maintainer asked: "We can create custom roles and add that to teams, but we cannot add that to API keys. Can we please add functionality where we can add custom roles to API keys as well?"

This is the team mechanism reused, not a second one:

• A new ApiKeyCustomRole row says "this key has this role". It sits beside TeamCustomRole and has the CRUD route /api-key-custom-role.
• When a key is given a role, the key gets an ApiKeyPermission copy of each of the role's permissions, with the same labels. CustomRoleSync creates these copies and keeps them in step with the role, as it does for teams. Each copy is marked with customRoleId, apiKeyCustomRoleId and customRolePermissionId, and the database deletes it when the role is deleted, taken away, or loses that permission (ON DELETE CASCADE).
• Every check that reads what a key may do already reads ApiKeyPermission. So a key's effective permissions include its roles with nothing new to get wrong: labels and scoping behave as for the key's own permissions.
• A permission that the role limits to resources someone owns gives the key nothing, because a key owns nothing. The docs already said keys don't support the Owned scope, and wherever the UI counts a role's permissions on a key it says how many apply ("2 of its 3 permissions apply to this key").

Safety

• No more than the role grants. Giving a role is checked as giving each of its key-applicable permissions to the key directly, with their labels. It goes through the key's own grant ceiling (ApiKeyPermissionService.assertCallerCanGrantPermission). A property test shows this ceiling is never looser than the team ceiling for a role's copies.
• Who may give a role. Only someone who may change what a key can do (Project Owner, Project Admin, Edit API Key Permissions) and who can read the role. Anyone else is refused with a message that says why.
• Removal is immediate.
  • The key's permission cache is keyed by a generation in CacheGenerations.
  • These all bump that generation: giving or taking a role, adding, changing or removing a permission of the role, and deleting the role. Every server then drops what it had read about the key.
  • A deleted role leaves no rows behind, because of the cascades.
• Copies are read-only. The API refuses any non-root update or delete of a copy. Change the role instead, or take it away from the key.
• Audit log. Each grant is logged under the key, named by the role (@EnableAuditLog).
• If the copies can't be made, the role is taken back off the key and the request is refused.

Where it shows

• A key's page: a new Custom Roles card above Permissions. Each role links to its page and shows how many of its permissions apply to the key. Add Custom Role offers only the roles the key doesn't have, and Remove says what the key keeps. The key's own Permissions list never shows the copies.
• A role's page: API Keys with this Role, below the teams, with Give to an API Key and Remove. The line about who a change reaches, and the Delete dialog, count keys too. Someone who may not read keys sees neither.
• Create API Key: the project's custom roles appear under Access, after the built-in roles. Only roles that would give the key something, and that the user could give, are listed.
• Roles page and delete wording now mention API keys.
• API reference and Terraform: generated from the model. This adds the oneuptime_api_key_custom_role resource (changing its key or role replaces it). oneuptime_api_key_permission can read the three copy columns but not set them.
• Docs: permissions/index.md and configuration/audit-logs.md, in all 17 languages.
• Dashboard strings: 34 new strings, in all 17 locales.

Migrations

• 1806500000000-AddApiKeyCustomRoles: the table with its indexes and FKs, plus the three columns on ApiKeyPermission.
• 1806510000000-AddApiKeyPermissionCustomRoleLinks: the copy columns' indexes and FKs, built with OnlineDdl outside a transaction.
• Both come after master's latest migrations. The schema drift check is clean.

Tests

• Copy plan: ApiKeyRoleCopyPlan.test.ts (seeded property tests).
• Sync, hooks and ceilings: CustomRoleSyncApiKeys.test.ts, ApiKeyCustomRoleService.test.ts, ApiKeyPermissionRoleCopies.test.ts and ApiKeyCeilingWithinTeamCeiling.test.ts.
• Against a migrated Postgres: ApiKeyCustomRolesPostgres.test.ts, 20 tests, added to the postgres-schema-drift workflow. It covers a role alone, a role beside the key's own permissions, label-scoped roles, Owned-scope permissions, a key's own block, two roles holding the same permission, cache invalidation on every kind of change, and refusals.
• API and Terraform: ApiKeyCustomRoleApiAndTerraform.test.ts, which reads the real OpenAPI spec and the real provider parser.
• Dashboard:
  • ApiKeyViewCustomRoles.test.tsx and RoleViewApiKeys.test.tsx;
  • Create API Key cases in ApiKeysCreateAccess.test.tsx;
  • CustomRoleRelationSelect.test.ts, which pins a relation-select bug on CustomRole.permissionCount that was fixed here;
  • the helper tests.
• Browser, offline: packages/E2E/CustomRoles/ApiKeyCustomRoles.spec.ts, 12 specs on the custom roles fixture (which now also mounts SettingsRoutes), at 1280 and 390 px and in dark mode.

Verification (local)

• Common: tsc and compile-tests pass. The guards, locale suites and this branch's suites pass, including with ee/ moved aside.
• Dashboard and App: tsc passes. Tests/Dashboard, the App root suites and Tests/FeatureSet/Docs all pass except CliDocsFacts. That suite fails on master too (master's DatabaseService sort change) and none of its files differ from master here.
• Postgres: all seven Postgres suites pass on a database migrated from scratch.
• Browser: the custom roles suite passes, 70 specs in 3.5 minutes.
• Strings and docs: i18n:check, i18n:validate and docs:check-anchors pass.

UI review

Looked at: every surface this PR adds or changes, rendered from the real pages through the offline custom roles fixture in headless Chromium (Inter loaded), at 1280 and 390 px, light and dark, in English, German and Japanese, with long names and empty, one-row and every-row states:

• a key's page: the Custom Roles card (full, empty, every role given), Add Custom Role, Remove, the bulk Remove;
• a role's page: Permissions with its reach line, Teams with this Role, API Keys with this Role, Give to an API Key (open list, last key, no key left, no key at all), Remove, Delete;
• Create API Key with custom roles under Access; the Roles page and the team pages beside them.

What was not great, and what changed:

• "2 of its 3 permissions apply to this key" never said why. The reason was only in the Add dialog, in words ("limited to resources someone owns") that match nothing on the role's page. The count now has an (i), reachable by mouse, keyboard and screen reader, that says it in the words of the role's Scope column: Permissions scoped to "Only resources they own" don't apply to an API key: a key owns nothing.
• A role's API Keys card was wrong for a role with an owned-only permission. It said "These API keys can do everything this role allows" above a role whose Alert Member is "Only resources they own". It now says These API keys get 2 of this role's 3 permissions: those scoped to "Only resources they own" don't apply to a key. When every permission is owned-only, it says none applies. It follows the role's permissions as they change: delete or rescope one and the card updates.
• The dialogs said the exception even when it did not apply. Add Custom Role and Give to an API Key now name it only when a role offered (or the role given) has an owned-only permission. In most projects none does, so the dialog is one short sentence.
• Give to an API Key could lead to a dead end. In a project with no API key, or once every key had the role, it opened a dialog whose list said "No options." It is now off, with the reason on hover. A project with no key gets an empty card that says so and links to the API Keys page.
• Phone cards repeated their column's name. On a phone, "Role" sat over every role on a key's card, and "API Key" and "Team" over every row on a role's page. These one-column tables now leave the name out on phones, for the team's own Custom Roles card too, so sibling pages match. Screen readers still hear it. ModelTable columns now type hideTitleOnMobile, which they already passed through to the table.
• The API reference and Terraform description of ApiKeyCustomRole now state the Owned exception (the builder left it out).
• CI time. The offline custom roles suite now takes 4.1 minutes with its bundle locally, about 1.2 more than on master. Group 7 took 21.5 minutes on master's last run, so Archivable Values moved to group 9, which took 18.9 to 19.4.
• Smaller fixes:
  • A hard-coded English fallback in the no-key link, which DashboardComponentsAToLHardcodedGuard flags.
  • A test pattern (/\d+ API keys?/) that the ReDoS checker found quadratic, now anchored at a word edge.
  • Two over-long comment lines and an orphaned comment.

Strings: 13 new sentences (one with its _one form) in all 17 locales, translated, with each language's own quote marks around the scope's name. The three builder sentences they replace are removed. i18n:check reports no translation lost.

Tests added or changed:

• CustomRoleCopy.test.ts: the reason, the API Keys card in every case (unknown, none, some and all owned, counts out of range), both dialog descriptions, German. Every new sentence is in en.json.
• CustomRoleOptions.test.ts: loadCustomRoleGrants reads one role when given a customRoleId; getApiKeyRoleCoverage.
• ApiKeyViewCustomRoles.test.tsx: the (i) only on a partial role, its accessible name and tooltip, an all-owned role, and the Add dialog with and without the exception.
• RoleViewApiKeys.test.tsx: the card and Give dialog for partial and all-owned roles, one role's permissions read, the card following a change of permissions, a project with no key (empty card, link, Give off with its reason), and every key having the role.
• ApiKeyCustomRoles.spec.ts (offline browser), 5 new and 4 updated specs:
  • the (i) on hover and keyboard focus;
  • Add Custom Role without the exception;
  • a role with nothing owned-only;
  • deleting the owned-only permission updates the card;
  • ?keys=none, with the link working;
  • Give off once every key has it;
  • no column name on phone cards.
• The fixture gains ?keys=none. ApiKeyCustomRoleApiAndTerraform.test.ts pins the new description.

Run locally:

• Common: the changed suites, all Locale suites, and npx jest Guard plus the guard-like suites (168 suites).
• App: the root-level suites, the Dashboard guard, locale, wiring and description suites, CustomRolesDocs and PermissionsAndSelfHostedDocsFacts (191 suites). The changed suites also ran with ee/ moved aside.
• Repo: Tests/Ops (64 suites).
• Browser: the whole offline custom roles suite, 75 specs.
• Type checks: Common tsc and compile-tests, App compile, Dashboard tsc and E2E tsc.
• Other checks: i18n:check, prettier and eslint on every changed code file, the --listFiles package check, and the ReDoS checker, which is clean.
• The 34 docs .md files this branch changes are not prettier-clean, and neither are master's copies of them.

Left as it was, on purpose:

• The key's Custom Roles card keeps its full empty state and its place above Permissions. A team's Permissions page does the same, and a key keeps looking like a team.
• A disabled card button (ButtonStyleType.NORMAL) still looks enabled, across the whole product. The tooltip says why it is off; restyling the shared Button is a change of its own.

🤖 Generated with Claude Code

[simlarsen]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.