orkeys (pronounced "ORKies") is an IaC for your LLM API keys. orkeys manages LLM API keys. It has two modes:
- Provider commands manage keys at one provider directly:
orkeys openrouter(or),orkeys deepinfra(di) andorkeys openai(oa). - Inventory mode manages keys of all providers from an inventory repository, with state and secrets in Vault or AWS, rotation, alerts and self-service keys (see Inventory mode).
Go (1.24 or later):
go install github.com/hatedabamboo/orkeys@latestBinaries: download an archive for Linux, macOS or Windows from
Releases, then put orkeys on your PATH.
From source:
git clone https://github.com/hatedabamboo/orkeys && cd orkeys
make installOpenRouter has full support. DeepInfra is read only: DeepInfra does not let an API key create, limit, disable or
delete tokens (see DeepInfra). Each write to DeepInfra fails with 401. OpenAI has no per-key limit and
no disabled flag: orkeys creates, rotates and deletes OpenAI keys, and tracks their budget only in metrics (see
OpenAI).
| Feature | OpenRouter (or) |
DeepInfra (di) |
OpenAI (oa) |
|---|---|---|---|
List keys (list) |
yes | yes. No scopes and no creation time | yes. Keys of users and service accounts |
Show one key (get) |
yes | yes | yes |
Create a key (create) |
yes | no | yes. One service account per key |
Change the limit (update --limit) |
yes | no | no per-key limit |
Limit period (--limit-reset) |
daily, weekly, monthly |
monthly only |
no per-key limit |
Expiry (--expires) |
yes | no | yes. At most 365d |
Rename (update --name) |
yes | no | no |
Change scopes (update --scopes) |
no scopes | no | yes |
List possible scopes (scopes) |
no scopes | yes | no |
Disable a key (disable) |
yes | no | no |
Enable a key (enable) |
yes | no command | no |
Delete a key (delete) |
yes | no | yes |
Workspaces (--workspace) |
yes | no | one project per call (--project), required |
| Spend shown | day, week, month, total | month | day, week, month |
| Last use shown | yes | no | yes |
| Feature | OpenRouter | DeepInfra | OpenAI |
|---|---|---|---|
validate, state |
yes | yes | yes |
plan |
yes | yes | yes |
apply: create a key |
yes | no | yes |
apply: set the limit |
yes | no | no. The budget is only a metric |
apply: disabled: true |
yes. Sets the disabled flag | no | no. validate rejects it |
apply: revoke a deleted manifest |
yes | no | yes |
budget.reset |
daily, weekly, monthly |
monthly only |
daily, weekly, monthly. Only a metric |
scopes field |
no | yes. Used only at create | yes. Used only at create |
rotate |
yes. The key also has a native expiry | no | yes. The key also has a native expiry. ttl at most 365d |
request, revoke |
yes | no | yes |
import: print manifests |
yes | yes | yes |
apply: adopt an import key |
yes | no | yes |
apply: track a key (track_only: true) |
yes | yes | yes |
hygiene: revoke keys of people who left |
yes | no | yes |
hygiene: find unused keys |
yes | no. DeepInfra has no last use | yes |
exporter: spend |
yes | yes. Spend this month only | yes |
exporter: hard limit |
yes | yes | no. Budget only |
exporter: last use |
yes | no | yes |
| Old key "still in use" check at revoke | total usage | spend this month | last use (exact), spend this month |
orkeys keys -p <provider> lists, creates, limits, disables, enables and deletes keys of any provider in
policy.yaml with the same commands for all providers. It does what all adapters can do; the provider commands
above show the fields of one API.
orkeys openrouter (alias or) uses the
Management API. To create a management key, go to
openrouter.ai/settings/management-keys.
A management key can only manage keys. It cannot call models.
| Variable | Required | Purpose |
|---|---|---|
OPENROUTER_MANAGEMENT_API_KEY |
yes | Management API key |
OPENROUTER_API_BASE |
no | API base URL. Default: https://openrouter.ai/api/v1 |
OPENROUTER_WORKSPACE_ID |
no | Workspace for list, create and lookup. Same as --workspace |
orkeys or list # all pages, active keys
orkeys or list -d -o wide # with disabled keys, all columns
orkeys or list --json | jq '.[] | select(.limit == null) | .name'
orkeys or get ci
orkeys or create --name ci --limit 20 --limit-reset monthly --expires 90d
KEY=$(orkeys or create --name tmp --expires 12h -q) # print only the secret
orkeys or update ci --limit none --limit-reset none --name ci-old
orkeys or disable ci-old 3f2a9c
orkeys or enable ci-old
orkeys or delete ci-old -yCommands that take <key> accept a full hash, a unique hash prefix or an exact key name.
DeepInfra cannot be automated with API keys. DeepInfra's own rule: "Some actions are never open to an API key, whatever its scopes, unrestricted included: managing API keys, changing payment details, setting spending limits and topping up all need a dashboard login" (docs). There is no documented API session for that login. So with any API key, orkeys can only read DeepInfra: token names, limits and spend. Creating, deleting, limiting or disabling tokens fails with
401, in thedicommands and in inventory mode.
orkeys deepinfra (alias di) shows API tokens with their monthly limit and spend.
| Variable | Required | Purpose |
|---|---|---|
DEEPINFRA_API_KEY |
yes | API key. Reads need the billing:read scope |
DEEPINFRA_API_BASE |
no | API base URL. Default: https://api.deepinfra.com |
orkeys di list # tokens with limit and spend this month
orkeys di get cilist and get read /payment/key-limits. An API key cannot list tokens (/v1/api-tokens), so scopes and creation
times are not shown. Commands that take <token> accept a token ID or an exact name.
The write commands (create, update, disable, delete, scopes) call the token and limit endpoints. They work
only with a credential that DeepInfra allows to manage keys; no API key qualifies today.
What we found about the alternative, scoped JWTs (POST /v1/scoped-jwt), tested on 2026-11-06:
- A JWT expires on time and cannot call management endpoints. A model allow-list is enforced.
spending_limitis a total for the JWT's life, and it works only with exactly one model.api_key_namepicks the key that signs and pays. Any key that may mint JWTs can bill any key in the account.- Only the signing key can read a JWT's spend (
GET /v1/scoped-jwt). - Retired model names are redirected to a new model, so a JWT for an old name is refused.
orkeys does not use JWTs. To manage DeepInfra traffic fully, route it through OpenRouter with DeepInfra as the provider: the keys are then OpenRouter keys.
orkeys openai (alias oa) uses the Admin API to
manage the API keys of one project. Create an Admin API key at
platform.openai.com/settings/organization/admin-keys.
An Admin API key cannot call models.
| Variable | Required | Purpose |
|---|---|---|
OPENAI_ADMIN_KEY |
yes | Admin API key |
OPENAI_PROJECT_ID |
yes | Project ID (proj_...). Same as --project |
OPENAI_API_BASE |
no | API base URL. Default: https://api.openai.com/v1 |
orkeys oa list # keys with spend this month
orkeys oa list -o wide # with owner, day and week spend
orkeys oa get ci
orkeys oa create --name ci --expires 90d
orkeys oa create --name reader --scopes api.all.read
KEY=$(orkeys oa create --name tmp --expires 12h -q) # print only the secret
orkeys oa update ci --expires 30d # new expiry, counted from now
orkeys oa delete ci -yLimits of the OpenAI Admin API:
- OpenAI has no per-key spend limit. In inventory mode, orkeys keeps
budgetonly as a metric (orkeys_key_budget_usd). Limits per project and per organization are set in the OpenAI dashboard. - OpenAI has no disabled flag.
deleteis the only way to revoke a key. - The Admin API cannot create a key for a user.
createmakes a service account with the key name, and then one key for it.deletedeletes the key, and also the service account when the account has no other keys. - A key cannot be renamed. The expiry is at most 365 days, and
update --expirescounts it from the time of the call. - Spend comes from the costs endpoint (
/organization/costs), in 1-day UTC buckets. OpenAI fills them with a delay, so the spend of today is not complete. A week starts on Monday.
Commands that take <key> accept a key ID or an exact key name.
Run orkeys <provider> <command> --help to see all flags.
-o table (default), -o wide or -o json. --json is a shorthand for -o json.
JSON output holds the full API objects. create --json includes the secret in key.
| Flag | Format |
|---|---|
--limit |
USD amount, or none to remove the limit |
--limit-reset |
OpenRouter only: daily, weekly, monthly or none. Resets happen at midnight UTC |
--expires |
OpenRouter only: duration (30d, 2w, 12h), date (2027-12-31, midnight UTC) or RFC 3339 |
deleteasks for confirmation. Without a terminal it refuses to run unless you pass--yes.delete,enableanddisabletake more than one key.deletefinds all the keys before it deletes any.- GET requests retry on HTTP 429 and 5xx, and use
Retry-After. Writes do not retry. - Exit code is
0on success and1on any error.
Debug logs show URLs, secret paths, key names and key IDs. Keep them out of public CI logs if these names are private.
--debug (or ORKEYS_DEBUG=true) writes debug logs to stderr. It works with all commands. --log-format json writes
them as JSON records. The flag has priority over the env.
Debug logs show:
- each HTTP call to a provider, Vault and GitHub: method, URL without the query, status, attempt, time, retries;
- each AWS call: service, operation, time, error;
- each
kubectlcall: arguments, exit code, time; each poll of an ExternalSecret; - the state lock: acquire, wait, renew, release;
- the inventory files that orkeys reads, and the state and secrets backends;
- the steps of
plan,apply,rotate,requestandhygiene: the data of each key, the decision, the secret writes, the consumer syncs, the revoke checks; - the exporter polls and the scrapes.
Debug logs do not show key values, management keys, tokens, request and response bodies, URL queries or the
--events-webhook URL.
orkeys completion zsh > "${fpath[1]}/_orkeys"
orkeys completion bash > /etc/bash_completion.d/orkeys
orkeys completion fish > ~/.config/fish/completions/orkeys.fishInventory mode manages keys of all providers from a git repository of YAML manifests. orkeys makes the providers, a secrets store and Kubernetes match the manifests, rotates keys before they expire, issues short-lived self-service keys, and exports spend and expiry as Prometheus metrics.
DeepInfra is read only. Provider support shows what works for each provider.
To start, copy examples/inventory and run orkeys validate --repo <dir>.
examples/inventory/.github/workflows has GitHub Actions workflows for
rotate (hourly) and hygiene (weekly). They log in to Vault with AppRole and write the events to the run summary.
| Command | What it does |
|---|---|
orkeys validate |
Check the repository against policy.yaml and the rules below. Needs no credentials |
orkeys plan |
Show the changes. --markdown for a PR comment, --json for scripts, --out <file> to save the plan for apply --plan |
orkeys apply |
Create, update and revoke keys; write manifest keys to the secrets store. Asks for confirmation; --yes in scripts. Refuses more than max_deletes revokes without --allow-deletes <n>. With --plan <file>, applies only if the plan is the same as the saved one |
orkeys rotate |
Rotate manifest keys before expiry, sync External Secrets, restart the listed workloads, revoke old keys after the grace period. Expire requested keys. Run it on a schedule (for example hourly) |
orkeys rotate --now <key> |
Rotate a manifest key now |
orkeys rotate --retry <key> |
Retry a failed rotation |
orkeys rotate --only <key> |
Process only these keys |
orkeys request --user <login> --kind <kind> --provider <name> --purpose <text> |
Issue a key of a kind with source: request, encrypted to the user's GitHub SSH keys. Optional --limit and --ttl, up to the kind maximum |
orkeys issued |
List active requested keys with owner, purpose, spend and expiry. Filters: --team, --owner, --kind. --markdown for a table |
orkeys revoke <name>... |
Revokes keys. Revoke requested keys before they expire: deletes the provider key, the secret fields and the GitHub secrets, and removes the state. Optional --reason. Asks for confirmation; --yes in scripts |
orkeys state [name] |
List the keys in the state store with source, owner, key ID, limit, expiry and rotation. Filters: --team, --kind, --owner, --provider, --source. With a name, print that state entry as JSON. Needs no management keys |
orkeys import |
Print a manifest with an import block for each provider key that orkeys does not manage. --track-only: print manifests with track_only: true and no secret |
orkeys hygiene |
Changes keys unless you pass --dry-run: revokes keys of people who left the GitHub org, lists unused keys |
orkeys unlock [id] |
Show the state lock, or remove it by ID after a crashed run |
orkeys exporter |
Serve spend, limits, expiry and rotation state as Prometheus metrics |
orkeys keys -p <provider> list|create|set-limit|disable|enable|delete |
Manage keys of one provider of policy.yaml directly. Changes no state: plan shows keys made here as unmanaged |
Point orkeys at the repository with --repo or ORKEYS_REPO.
Global flags for inventory commands:
| Flag | Env | Meaning |
|---|---|---|
--events-file <path> |
ORKEYS_EVENTS_FILE |
Append each event to the file as one JSON line, at the time of the event. A killed run keeps its events |
--events-webhook <url> |
ORKEYS_EVENTS_WEBHOOK |
POST each event as JSON to the URL. orkeys tries 3 times. Errors do not show the URL |
--log-format text|json |
Progress logs on stderr as plain lines (default) or as JSON records. Debug logs use the same format | |
--debug |
ORKEYS_DEBUG |
Write debug logs to stderr. See Debug logs |
applyrefuses a plan that revokes more thanmax_deleteskeys (default 3), before it changes anything. A checkout of the wrong branch or a missingteams/directory shows every key as removed. Check the plan, then runapply --allow-deletes <n>.planshows a warning for such a plan.plan --out plan.jsonsaves the plan with a fingerprint of its actions.apply --plan plan.jsonmakes a new plan under the lock and stops if it differs from the saved one, soapplydoes only what the reviewer saw.- When the run gets SIGINT or SIGTERM, orkeys starts no new action. The cleanup of a half-done action (delete a new key, restore a secret, save the state) still runs, for at most 30 seconds per step.
policy.yaml global settings and rules
teams/<team>/team.yaml team routing channels; members or a GitHub team
teams/<team>/<key>.yaml one manifest key per file; file name = key name
Unknown fields are errors, so a typo does not pass silently.
| Field | Default | Meaning |
|---|---|---|
state |
vault://secret/orkeys/state |
State store: vault://<mount>/<path> or s3://<bucket>/<prefix> |
secrets |
vault |
Secrets store: vault or aws (Secrets Manager) |
providers[] |
Provider accounts. A list of {name, kind, ...}, or a map from name to config. See Providers |
|
providers[].name |
Name used in manifests (provider:), kinds, state and metrics. Matches ^[a-z][a-z0-9-]*$ |
|
providers[].kind |
the name | Provider type: openrouter, deepinfra or openai |
providers[].management_key |
Secret path with field key (and optional self_id, workspace, base_url, and the provider options). Optional if ORKEYS_<NAME>_KEY is set |
|
providers[].workspace, base_url |
OpenRouter workspace or OpenAI project ID; API base URL | |
providers[].options |
Settings of the provider. All types: report_unmanaged, ignore_disabled, ignore_unmanaged (see Keys without a manifest) and track_only (see Tracking a key). openai: project (the project ID, required here or in workspace). Unknown options are errors |
|
envs |
[prod, staging, dev] |
Allowed env values of manifests |
name_prefix |
{env}-{team}- |
Required start of key names. {env} and {team} are replaced. "" turns the check off |
naming |
^[a-z0-9][a-z0-9._-]*$ |
Regex that every key name must match |
kinds.<name> |
Key kinds. At least one is required. See below | |
clusters.<name>.context |
cluster name | kubectl context for a cluster used in consumers |
github.org |
Org for owner checks in hygiene and for team members from GitHub teams |
|
github.api_url, github.keys_url |
https://api.github.com, https://github.com |
For GitHub Enterprise |
track_disabled |
false |
true: plan also enables manifest keys that are disabled at the provider but not in the manifest. See Disabling a key |
max_deletes |
3 |
Most keys that one apply revokes because their manifests are gone. apply --allow-deletes <n> raises it for one run. See Apply safety |
Each entry is one provider account. kind sets the provider type, and name is how manifests refer to it. Two
entries can have the same kind, for example two OpenRouter accounts or two workspaces of one account:
providers:
- name: openrouter-private
kind: openrouter
management_key: secret/orkeys/providers/openrouter-private
- name: openrouter-public
kind: openrouter
management_key: secret/orkeys/providers/openrouter-public
- name: deepinfra # kind defaults to the name
management_key: secret/orkeys/providers/deepinfra
- name: openai
management_key: secret/orkeys/providers/openai # an Admin API key
options:
project: proj_abc123 # the project that holds the keysThe map form still works. The map key is the name, and the kind defaults to it:
providers:
openrouter:
management_key: secret/orkeys/providers/openrouter
openrouter-public:
kind: openrouter
management_key: secret/orkeys/providers/openrouter-publicThe env var override uses the name in upper case, with - as _: openrouter-private reads
ORKEYS_OPENROUTER_PRIVATE_KEY and ORKEYS_OPENROUTER_PRIVATE_SELF_ID.
Do not point two entries at the same keys: two management keys of one OpenRouter account without different
workspace values. Then each entry lists the keys of the other as unmanaged.
The state stores the provider name of each key. Do not rename a provider that has keys: plan then shows
"provider or kind changed". To move keys to a new name, add manifests with new key names.
You name the kinds and set their values. A kind name matches ^[a-z][a-z0-9-]*$. The source of a kind sets how
its keys are made and how they end:
manifest: keys come from manifests inteams/. orkeys writes them to the secrets store and rotates them before they expire.request: keys come fromorkeys request. orkeys encrypts them to the owner. They expire atttland are not renewed. Requested key names are<kind>-<login>-<time>, so no manifest name can start with<kind>-.
| Field | Source | Default | Meaning |
|---|---|---|---|
source |
all | manifest |
manifest or request |
ttl |
all | required | Manifest keys: the default and the longest allowed ttl. Requested keys: the default and the longest --ttl |
providers |
all | all in providers |
Providers allowed for this kind |
budget.reset |
all | monthly |
Default limit period: daily, weekly or monthly. Requested keys always use it |
budget.limit |
all | max_limit |
Default limit in USD when the manifest or the request gives none |
max_limit |
all | none (required for request) |
Highest allowed limit |
rotate_before |
manifest |
3d |
Start rotation this long before expiry. Must be shorter than ttl |
revoke_grace |
manifest |
24h |
Keep the old key this long after consumers switched |
notify_before |
request |
none | Send expiry_notice this long before expiry |
max_active |
request |
none | Active keys of this kind per person |
max_total_limit |
request |
none | Sum of limits of this kind per person |
kinds:
production:
ttl: 90d
budget: {reset: monthly, limit: 100}
batch: # short-lived job keys, rotated monthly
ttl: 30d
rotate_before: 1d
budget: {reset: daily}
max_limit: 50
providers: [openrouter]
personal:
source: request
ttl: 14d
budget: {limit: 25}
max_limit: 100
max_active: 3
notify_before: 3d
providers: [openrouter]If you remove a kind from the policy while keys of it exist, plan and rotate keep the requested keys of that kind
and revoke them at expiry. rotate fails for manifest keys of that kind until the kind is back or the manifests use
another kind.
team: search # must match the directory name
channels:
notifications: "#search-notifications" # info events; alerts of keys of source: request kinds
alerts: "#search-alerts" # alerts of keys of source: manifest kinds
github_team: search-eng # optional; GitHub team slug if it is not the team name
# members: [alice, bob] # optional; static GitHub logins instead of a GitHub team| Event level | Key kind source |
Channel |
|---|---|---|
info |
all | channels.notifications |
alert |
request |
channels.notifications |
alert |
manifest |
channels.alerts |
kinds.<kind>.alert_channel is deprecated. orkeys ignores it and prints a warning.
Members of a team may request keys. orkeys reads them from one of two places:
- GitHub team (default). Without
members, orkeys uses the teamgithub.com/orgs/<github.org>/teams/<slug>. The slug isgithub_team, orteamifgithub_teamis not set. Members of child teams count. Pending invitations do not count. This needsgithub.organdGITHUB_TOKENwithread:org. - Static list.
members: [alice, bob]sets the GitHub logins in the file. No token is necessary.
members and github_team together are an error. validate does not use the network. plan warns about a GitHub
team that does not exist, if GITHUB_TOKEN is set.
Channels are optional. orkeys sends nothing itself: it puts the channel on events and metrics, so a downstream service (Alertmanager, a CI step, a bot) can route them.
| Field | Required | Meaning |
|---|---|---|
name |
yes | Same as the file name. Must match naming and start with name_prefix |
kind |
yes | A kind with source: manifest |
provider |
yes | A provider name from providers, allowed by the kind |
env |
yes | One of envs |
service |
no | Free text; exported as a metric label |
description |
yes | |
scopes |
no | DeepInfra and OpenAI. DeepInfra default: [inference]; unrestricted is not allowed. OpenAI default: all permissions of the service account; for example [api.all.read] |
budget.limit |
no | Limit in USD at the provider; the provider blocks the key when spend in the period reaches it. OpenAI has no per-key limit: orkeys only exports the budget as a metric. Default: the kind budget.limit. Up to the kind max_limit |
budget.reset |
no | Limit period: daily, weekly, monthly (DeepInfra: monthly only). Default: the kind budget.reset |
ttl |
no | 90d, 2w, 24h. Default and maximum: the kind ttl. OpenAI: at most 365d |
secret.path, secret.field |
path: yes, except with track_only: true |
Where the key goes. Vault: <mount>/<path>; AWS: secret name. Field default api_key. Other fields in the same secret are kept. secret is one mapping or a list of mappings: orkeys writes the same key to each place. Two keys can share a path, not a path and field |
consumers[] |
no | type (eso, direct or github). For eso and direct: cluster, namespace, externalsecret (eso), restart (deployment/x, statefulset/x, daemonset/x, cronjob/x). orkeys restarts only what restart lists. For github: repo (owner/repo) or org, environment (repo only), name, visibility (org only: private (default) or all), workflows (repo only: a list of {workflow, ref, inputs} to run after each write). See GitHub Actions secrets. A field of another type is an error |
import.id, import.name |
no | Adopt an existing provider key instead of creating one. name is its current name at the provider. See below |
disabled |
no | true disables the key at the provider and stops its rotation. Default false. Not for OpenAI keys. See below |
track_only |
no | true: orkeys saves the state of the import key and exports its metrics, and does not change the key. Default: the provider option track_only. false on a key of a provider with track_only: true makes a managed key. See Tracking a key |
secret: # one key in two places; each rotation updates both
- path: kv/llm/prod/search/env
field: api_key
- path: kv/llm/staging/search/env
field: OR_API_KEY
consumers:
- type: eso # force-sync, then restart the API
cluster: prod-eu
namespace: search
externalsecret: search-llm
restart: [deployment/search-api]
- type: eso # force-sync only; the worker reloads the mounted secret
cluster: prod-eu
namespace: search
externalsecret: search-worker-llmLimits:
- orkeys writes a second copy of the key into GitHub. GitHub secrets are write-only, so orkeys cannot read them back to check them. "Synced" means "the write succeeded".
- The token can write secrets in all the repos it can access. Give it access only to the repos in the manifests.
- If you control the workflows, prefer a
directconsumer with norestart. Then the workflow reads Vault or AWS with GitHub OIDC (hashicorp/vault-action,aws-actions/configure-aws-credentials), and no copy exists.
A github consumer is a GitHub Actions secret. orkeys writes the key to it:
applywrites it when it creates or imports the key.planshowssync-consumerswhen the manifest adds agithubconsumer, or when a write failed before.applywrites the new secrets and deletes the secrets of removedgithubconsumers.rotatewrites the new key during the consumer sync. If a write fails, the rotation fails and the old key stays active. Fix the cause, then runorkeys rotate --retry <key>.- When you delete the manifest,
applydeletes the GitHub secrets first, then revokes the key. - With
workflows, orkeys starts aworkflow_dispatchrun of each listed workflow inrepoafter each write of the secret. See Workflow runs.
secret: # one key in two places; each rotation updates both
- path: kv/llm/prod/search/env
field: api_key
- path: kv/llm/staging/search/env
field: OR_API_KEY
consumers:
- type: github # repository secret
repo: acme/search
name: OPENROUTER_API_KEY
- type: github # environment secret
repo: acme/search
environment: prod
name: OPENROUTER_API_KEY
- type: github # organization secret, visible to private repos
org: acme
name: SEARCH_OPENROUTER_KEYThe token is ORKEYS_GITHUB_SECRETS_TOKEN, or GITHUB_TOKEN if it is not set. It needs "Secrets: read and write"
on the repositories (fine-grained token or GitHub App), and "Organization secrets: read and write" for org. The
default GITHUB_TOKEN of a workflow cannot write secrets. A workflow that is running during a rotation keeps the old
value until its next run; revoke_grace covers this.
If a consumer still uses the old key after revoke_grace, its spend grows and orkeys does not revoke the old key
(old_key_in_use). So a consumer without restart must pick up the new secret by itself.
Add, remove or change a place in secret to move a key: orkeys rotates it, writes the new key to all places in the
list, and removes the fields of removed places after the revoke. Delete the manifest to revoke the key; orkeys removes
only its own fields from the secrets.
Limits:
workflowsis forrepoconsumers only. Organization secrets have no repository to run a workflow in.- The workflow must have a
workflow_dispatchtrigger. GitHub rejectsinputsthat the trigger does not declare. - orkeys starts the run and does not wait for it. A failed run does not fail the rotation. Watch the run in GitHub.
- orkeys does not start runs when you add
workflowsto a consumer that already holds the current key. The first runs come with the next write: a rotation, or a change ofsecret. - If one start fails, the retry starts all workflows of the consumer again, also the ones that started.
- Two
github 10BC8consumers with the same workflow start two runs. - One consumer can list the same
workflowmore than once with anotherrefor otherinputs. Each entry starts one run. Two entries with the sameworkflow,refandinputsare an error. An error of a start names its entry:workflows[1].
Use workflows when a deploy workflow reads the secret and the service gets the key only from a deploy. After each
write of the secret (create, import, rotation, reissue), orkeys starts a run of each workflow in the list:
consumers:
- type: github
repo: acme/search
name: OPENROUTER_API_KEY
workflows:
- workflow: deploy.yml # file in .github/workflows, or a workflow ID
ref: main # branch or tag to run on; default: the default branch
inputs: {environment: prod} # workflow_dispatch inputs; optional
- workflow: deploy.yml # same workflow again: a second run with other inputs
ref: main
inputs: {environment: canary}
- workflow: smoke-test.yml # runs on the default branch with no inputsIf a start fails, the write counts as failed. At rotate, the rotation fails and the old key stays active. Fix the
cause, then run orkeys rotate --retry <key>: orkeys writes the secret again and starts the workflows again. At
apply, the next plan shows sync-consumers.
The token needs "Actions: read and write" on the repository, in addition to "Secrets: read and write".
Set disabled: true in the manifest to stop a key and keep its state and secret. plan shows disable, and apply
disables the key at the provider (key_disabled event). OpenRouter has a disabled flag. DeepInfra has none, so orkeys
sets the limit to 0. OpenAI has neither, so validate rejects disabled: true on OpenAI keys; delete the manifest to
revoke the key. A new or imported key with disabled: true is disabled right after apply creates or adopts it.
A disabled key does not rotate, and rotate --now fails for it. plan does not change its limit, and hygiene does
not report it as unused. An OpenRouter key still has its native expiry; after it expires, plan recreates it as a
disabled key.
Remove disabled: true (or set false) to enable the key again. This works only with track_disabled: true in
policy.yaml:
track_disabled |
Manifest disabled: true, key active |
Manifest not disabled, key disabled at the provider |
|---|---|---|
false (default) |
disable |
nothing; the key stays disabled |
true |
disable |
enable, then the limit is set from budget (key_enabled event) |
With track_disabled: true, a key disabled by hand (orkeys or disable) is enabled again on the next apply.
The state saves the manifest value of disabled. The exporter uses it in orkeys_key_disabled to tell a planned
disable from a disable outside orkeys. A state from orkeys before v0.4.3 has no such field: the first plan shows
update-state with disabled false -> true for each disabled key. With track_disabled: false, the removal of
disabled: true also gives update-state: the key stays disabled, and orkeys_key_disabled shows 2.
track_disabled is also the default for provider keys without a manifest. With false, plan, orkeys import and
the exporter ignore such keys when they are disabled. With true, they report them. The provider option
ignore_disabled replaces this default for one provider. See Keys without a manifest.
A key made outside orkeys (for example in the provider dashboard) can be managed like any other key. orkeys adopts it instead of creating a new one. orkeys never revokes or disables a key that has no manifest.
- Run
orkeys import. It prints a manifest for each provider key without state, withimport.idandimport.namefilled in and the current limit asbudget. - Write the current key value to
secret.path(fieldsecret.field, defaultapi_key). With a list of places, write it to the first place;applycopies it to the others. orkeys cannot read a key value from the provider. - Save the manifest as
teams/<team>/<name>.yaml, fill in theTODOfields and open a PR.
name: prod-search-api
kind: production
provider: openrouter
env: prod
description: Search API
import:
id: 3f2a9c1b7e04d5a6...
name: search-api # current name at the provider
budget: {reset: monthly, limit: 500}
secret: {path: secret/llm/prod/search/api}plan shows import and checks that a key with import.id exists, has the name import.name, and is not managed yet.
apply reads the secret and fails if the field is empty, sets budget at the provider, and saves the state. It
creates no key and restarts nothing. The key expires at import time + ttl, or earlier if the provider has an earlier
expiry. From then on the key rotates like any other key. After the import, the import block has no effect; you can
delete it.
Limits:
- orkeys does not change a tracked key. It does not set its limit, write it to the secrets store, sync consumers,
rotate it, disable it or revoke it. The provider does not stop the key at
budget.limit. budget.resetmust bemonthly. DeepInfra reports spend only for the current month.validaterejectssecret,consumersanddisabled: trueon a tracked key.importis required.
Use track_only: true for a key that orkeys cannot or must not manage, for example a DeepInfra key or a key that
another tool rotates. orkeys keeps a state entry with the key ID, team, env, service, channels and budget. The
exporter then shows the key metrics with the team labels, so the spend and budget alert rules work for it. It shows
orkeys_key_track_only 1 for the key. Alert rules use this series to tell a tracked key from a managed key.
- Run
orkeys import --track-only. It prints a manifest withtrack_only: trueand nosecretfor each provider key without state. - Save the manifest as
teams/<team>/<name>.yaml, fill in theTODOfields and open a PR.
name: prod-search-legacy
kind: production
provider: deepinfra
env: prod
service: legacy
description: Legacy reranker, key made in the DeepInfra dashboard.
import:
id: 3f2a9c1b7e04d5a6...
name: reranker # current name at the provider
track_only: true # orkeys exports the spend and does not change the key
budget: {limit: 300} # alert budget per month; not set at the providerTo track all keys of a provider, set track_only: true in its options. A key of that provider with
track_only: false is a managed key. orkeys request refuses a provider with track_only: true.
providers:
deepinfra:
management_key: secret/orkeys/providers/deepinfra
options:
track_only: true # manifests of DeepInfra keys only track themWhen you set track_only: true on a provider that has managed keys, validate fails for their manifests: they have
secret and no import. Set track_only: false in each of them. orkeys does not convert a managed key to a tracked
key.
| Change | Effect at apply |
|---|---|
| New manifest | track: saves the state. Reads no secret and changes nothing at the provider (key_tracked event) |
Change budget, service, env or the team channels |
update-state: changes only the state |
Change import.id |
track: the state gets the new key ID. The old key stays at the provider |
| Delete the manifest | untrack: removes the state entry. The key stays at the provider (key_untracked event). Does not count against max_deletes |
Remove track_only |
Nothing. plan shows a warning. To manage the key, delete the manifest and apply, write the key to secret.path, then add the manifest with import and without track_only |
Add track_only: true to a managed key |
Nothing. plan shows a warning. Add a key with a new name instead |
rotate and hygiene skip tracked keys, and orkeys revoke refuses them. orkeys state shows tracked in the
ROTATION column. The exporter shows orkeys_key_hard_limit_usd from the limit that the provider reports, and no
orkeys_key_expires_timestamp_seconds when the provider key has no expiry.
Limits:
ignore_unmanagedtakes key IDs only. Key names are not unique at the providers, so a name does not identify a key.- An ignored key has no state and no metrics. orkeys does not see its spend.
- The management key secret cannot set these options. Set them in
policy.yaml.
plan lists provider keys that have no state, and the exporter counts them in orkeys_unmanaged_keys. Use an alert
rule on this metric to find keys made outside orkeys. Use the options of each provider to change what they report:
| Option | Default | Meaning |
|---|---|---|
report_unmanaged |
true |
false: plan does not show keys of this provider without state, and the exporter does not export orkeys_unmanaged_keys for it. orkeys import still prints them |
ignore_disabled |
the opposite of track_disabled |
true: plan, orkeys import and the exporter skip keys that are disabled at the provider |
ignore_unmanaged |
Key IDs that plan, orkeys import and the exporter never report |
providers:
openrouter:
management_key: secret/orkeys/providers/openrouter
options:
ignore_disabled: true # skip keys disabled at OpenRouter
ignore_unmanaged:
- 3f2a9c1b7e04d5a6... # CI key of the platform team, managed in Terraform
openai:
management_key: secret/orkeys/providers/openai
options:
project: proj_abc123 # the project that holds the keys
report_unmanaged: false # other teams make keys in this projectThe key ID is the OpenRouter key hash, the DeepInfra token ID or the OpenAI key ID. orkeys keys -p <provider> list
and the plan output show it. A disabled key is an OpenRouter key with the disabled flag, a DeepInfra key with a
limit of 0, or an OpenAI key with inactive project access.
plan shows a warning for an ID in ignore_unmanaged that is not at the provider or that has state. Remove such
entries.
orkeys does not send notifications. Commands that change keys (apply, rotate, request, revoke, hygiene) emit
events, and you route them with the tool you already have.
- Text mode (default): each event is one line on stdout, for example
[alert] rotation_failed prod-search-embeddings: rotation failed: .... Progress logs go to stderr. --events-fileand--events-webhookget each event at the time it happens. See the global flags under Commands. Use them in CI: a run that is killed prints no JSON document.- JSON mode (
-o jsonor--json): the command prints one JSON document on stdout at the end, also when it fails:
{
"plan": { "actions": [ ... ] },
"events": [
{
"time": "2026-11-06T12:00:00Z",
"level": "alert",
"type": "rotation_failed",
"key": "prod-search-embeddings",
"kind": "production",
"team": "search",
"provider": "openrouter",
"channel": "#search-alerts",
"message": "rotation failed: ...; the old key stays active; after the fix run: orkeys rotate --retry prod-search-embeddings",
"run_url": "https://github.com/acme/keys/actions/runs/123"
}
],
"error": "1 key failed"
}The result key depends on the command: plan (apply), issued (request), revoked (revoke), findings (hygiene);
rotate has only events. apply -o json and revoke -o json need --yes. The exit code is 1 when error is set.
Event type |
Level | When |
|---|---|---|
key_issued |
info | A key was created |
key_imported |
info | An existing provider key was adopted |
key_tracked |
info | apply saved the state of a key with track_only: true |
key_untracked |
info | apply removed the state of a tracked key whose manifest is gone. The key stays at the provider |
key_revoked |
info | A key was revoked (manifest removed, expired, owner left, orkeys revoke) |
key_disabled |
info | A key was disabled (disabled: true in the manifest) |
key_enabled |
info | A disabled key was enabled again (track_disabled: true) |
rotation_started |
info | A new key was written; consumers sync next. Level alert when orkeys issued the key because an earlier run stopped before it wrote its key to the secrets |
rotation_synced |
info | Consumers use the new key; the old key will be revoked after revoke_grace |
old_key_revoked |
info | The old key of a rotation was revoked |
expiry_notice |
info | A self-service key expires within notify_before |
rotation_failed |
alert | A consumer did not sync or restart; the old key stays active |
old_key_in_use |
alert | The old key was used after the switch; it is not revoked |
consumers_synced |
info | apply wrote or deleted push consumer targets (GitHub Actions secrets) |
consumers_sync_failed |
alert | A push consumer write or delete failed; the next apply tries again |
level picks channel: info uses the team's channels.notifications, alert uses channels.alerts.
run_url is set when orkeys runs in GitHub Actions.
Inventory mode needs two stores:
- State (
state). One entry per key: provider key ID, expiry, rotation progress, keys waiting for revoke, owner and purpose of requested keys. Without it, orkeys cannot link a manifest to a provider key.vault://<mount>/<path>: Vault KV v2, one secret per key.s3://<bucket>/<prefix>: one JSON object per key,<prefix>/<key name>.json.- Each write is conditional: Vault check-and-set on the version, S3
If-Matchon the ETag (If-None-Matchfor a new key). A write over a state that changed since it was read fails, and orkeys does not retry it. - Each state has a
schemaversion. orkeys refuses to run with a state from a newer orkeys: an older build would drop the fields that it does not know. Upgrade all runners (CI and laptops) together. .heartbeatholds the time of the last successfulapply,rotate,hygiene,requestandrevoke. The exporter shows it asorkeys_last_success_timestamp_seconds..policyholds a copy ofpolicy.yaml(.policy.jsonin S3). A successfulapplywrites it when the file changed, also when the plan is empty. A failed write failsapply, after the key changes. The exporter reads this copy, so it needs no second copy of the file.- Keep the history: turn on S3 bucket versioning, or keep
max_versionsabove 1 on the Vault KV mount. It is the audit trail and the way back after a bad change.
- Secrets (
secrets). Manifest keys, and by default the provider management keys.vault: Vault KV v2. A path is<mount>/<path>; fields are secret fields. Manifest keys get custom metadata per field:orkeys-key.<field>,orkeys-key-id.<field>,orkeys-team.<field>. Field writes and deletes use check-and-set, so a change by another client between the read and the write is not lost.aws: AWS Secrets Manager. A path is the secret name; the value is a JSON object, fields are its keys. Manifest keys get the same names as tags. A field name has only letters, digits, spaces and_.:/=+-@. A secret deleted by orkeys keeps a 7-day recovery window. When orkeys writes to a secret in that window, it restores the secret and writes only the new field.- A field name has at most 114 characters: Vault metadata keys and AWS tag keys have at most 128.
- Two keys can use the same path with different fields. Each field has its own metadata.
- orkeys up to v0.4.1 wrote one set of metadata per secret (
orkeys-key-idwithout a field). orkeys reads it for a field that has no metadata of its own. The next write to the secret removes it. planreadsorkeys-key-id.<field>of each place. When a place holds another key than the state,planshowsreissue: orkeys writes a new key to all places. orkeys writes the value before the metadata, so the metadata always names the key in the field.
S3 and Secrets Manager together let orkeys run with no Vault.
| Works without stores | Needs the stores |
|---|---|
validate, and the provider commands (orkeys or ..., orkeys di ...) |
plan, apply, rotate, request, issued, revoke, state, import, hygiene, unlock, exporter |
Read-only commands (plan, issued, import) need read access to the state and to the management keys. state
needs read access to the state only.
| Variable | Used by | Purpose |
|---|---|---|
VAULT_ADDR, VAULT_NAMESPACE |
Vault stores | Vault address and optional namespace |
VAULT_TOKEN |
Vault stores | Vault token. Or VAULT_ROLE_ID + VAULT_SECRET_ID (AppRole, mount VAULT_APPROLE_MOUNT, default approle), or VAULT_K8S_ROLE (Kubernetes auth, mount VAULT_K8S_MOUNT, default kubernetes) |
VAULT_CLIENT_CERT, VAULT_CLIENT_KEY |
Vault stores | PEM client certificate and key for mTLS (for example, Vault behind Teleport app access). Set both or none |
VAULT_CACERT |
Vault stores | PEM CA bundle for the Vault server, added to the system CAs |
AWS_REGION, AWS_PROFILE, ... |
S3 and Secrets Manager | Standard AWS SDK credential chain: env vars, profile, web identity (GitHub OIDC), pod role |
ORKEYS_<PROVIDER>_KEY, ORKEYS_<PROVIDER>_SELF_ID |
all except validate | Management key and its ID; override management_key |
GITHUB_TOKEN |
request, hygiene, plan | Team members from GitHub teams and org membership checks (read:org). Without it, request fails for a GitHub team, hygiene skips owner checks, plan skips team checks |
ORKEYS_GITHUB_SECRETS_TOKEN |
apply, rotate | Writes GitHub Actions secrets for github consumers and starts their workflows. Default: GITHUB_TOKEN |
AWS permissions: s3:GetObject, s3:PutObject, s3:DeleteObject on <bucket>/<prefix>/* and s3:ListBucket on the
bucket; secretsmanager:GetSecretValue, DescribeSecret, CreateSecret, PutSecretValue, TagResource, UntagResource,
DeleteSecret, RestoreSecret on the secrets orkeys reads and writes. The exporter needs only s3:GetObject, s3:ListBucket and
GetSecretValue.
apply, rotate, request, revoke and hygiene (without --dry-run) hold a lock on the state, the same way Terraform's S3
backend does with use_lockfile:
- S3: orkeys creates
<prefix>/.lockwith a conditional write (If-None-Match: *). A second writer gets412 Precondition Failed. Renew and takeover useIf-Matchwith the ETag. This is not S3 Object Lock, which is write-once retention, not a mutex. - Vault: orkeys creates
<path>/.lockwith check-and-set (cas=0creates only if absent;cas=Nupdates only version N).
The lock lives 15 minutes and the holder renews it every 5 minutes. A crashed run's lock expires, and the next run
takes it over. If the lock is held, a run waits up to --lock-wait (default 5m), then fails with the holder, the
operation and the lock ID. orkeys unlock shows the lock; orkeys unlock <id> removes it. apply holds the lock
across plan, confirmation and apply.
If a holder loses its lock, it stops and writes no more state. The lease also counts as lost when renewals fail (a store outage) until 2.5 minutes before the lock expires: another run can take an expired lock, so the holder stops first. After a failed renewal, orkeys tries again every minute.
Limit: release reads the lock and then deletes it. Neither store has a conditional delete here, so a release that races with a takeover of an expired lock can remove the new holder's lock.
- When a manifest key is
rotate_before(3d) from expiry,rotatecreates a new key, saves the state with phaseissuing, writes the key to all places insecret, and saves the state again without the phase. If a write fails, orkeys puts the old values back in the places it already wrote, deletes the new key and restores the state. If the run stops between the two state writes, the nextplanshowsresume, and the nextapplyorrotatefinishes the change: it copies the new key from a place that has it, or, when no place has it, issues another key and treats the lost key as an old key. - For each
esoconsumer, it annotates the ExternalSecret withforce-syncand waits until it is Ready with a newerrefreshTime. Then it runskubectl rollout restartandrollout statusonly for the targets inrestart. A consumer with norestartis not restarted: use this for workloads that reload the secret by themselves (a mounted secret volume, or an app that reads Vault on each request).directconsumers (workloads that read the secrets store themselves) get no force-sync, only theirrestarttargets. CronJobs are not restarted; the next run reads the new secret.githubconsumers get the new key written to their GitHub Actions secrets, and orkeys starts theirworkflows. - 15 minutes after the switch, a
rotaterun records the old key's usage (total usage on OpenRouter, spend this month on DeepInfra and OpenAI). OpenAI reports spend with a delay, so use arevoke_graceof at least 24h for OpenAI keys. Afterrevoke_grace(24h),rotatecompares it again. If the usage grew, a consumer still has the old key: orkeys does not revoke it and marks the rotation as failed. For OpenAI keys a last use after the switch also counts, because OpenAI reports it without delay. If the spend went down (a new month started), orkeys records a new baseline and decides on the next run. If no run recorded the usage in between, the run at revoke time records it and the next run revokes. Runrotatehourly. - A failed rotation sends an alert and stops. Fix the cause, then run
orkeys rotate --retry <key>. The old key stays active until then.
OpenRouter and OpenAI keys also get a native expiry at ttl. DeepInfra keys have none; orkeys revokes them itself.
Keys of a kind with source: request have no manifest. A team member requests one with a purpose. orkeys checks the
kind limits per person and keeps owner, team and purpose in the state. Alerts go to the team
channels.notifications. At expiry, rotate revokes the key and deletes its state; there is no renewal. If the kind has
notify_before, orkeys emits expiry_notice that long before expiry.
To revoke a requested key before expiry, run orkeys revoke <name>. Get the name from orkeys issued. Do not use
orkeys or delete for this: it deletes the provider key and keeps the state, and the key still counts against
max_active and max_total_limit until it expires. If the provider key is already deleted, orkeys revoke removes the
state. orkeys revoke refuses manifest keys: delete the manifest or set disabled: true.
orkeys finds the team of --user in members or in the GitHub team. If the user is in more than one team, request
fails and lists the teams: give one with --team <name>. With --team, orkeys checks only that team. A missing
GitHub team or a missing GITHUB_TOKEN is an error, not "not a member".
The keys are not stored in the secrets store. orkeys encrypts them with age to the owner's SSH keys
(ssh-ed25519 or ssh-rsa) from <github.keys_url>/<login>.keys and writes <name>.age to --out.
Decrypt with age -d -i ~/.ssh/id_ed25519 <file>.
hygiene revokes requested keys whose owner is not in github.org. GitHub answers 404 both for "not a member"
and for a wrong org name or a token without access, so before any revoke orkeys checks that the org exists and that
at least one team member (from members or from the GitHub team) is reported as a member. A GitHub team that does
not exist also stops the check. If not, it revokes nothing and fails. A user who renamed
their GitHub login is reported as gone; they can request a new key. Run --dry-run first.
Limits:
- A provider that is new in the stored
policy.yamlgets no metrics until the exporter restarts. The exporter makes the provider clients at start. It logs the new provider name. - The stored copy exists only after the first
applywith orkeys v0.4.3 or later. - The stored copy cannot change the state store. The exporter always uses
--stateto find it.
orkeys exporter --state vault://secret/orkeys/state # secrets and providers from the copy of policy.yaml in the state store
orkeys exporter --policy /etc/orkeys/policy.yaml # state, secrets and providers from the file
orkeys exporter --state s3://my-bucket/orkeys/state --secrets aws \
--provider openrouter=orkeys/providers/openrouter # flags override the policyWithout --policy, the exporter reads the copy of policy.yaml that apply saves in the state store (.policy).
It reads the copy again at each poll, so a change of the provider options (for example ignore_unmanaged) needs no
restart. It ignores fields that it does not know: CI can run a newer orkeys than the exporter. When the copy is
missing or broken, the exporter logs the error, keeps the last good policy and stops the update of
orkeys_policy_last_load_timestamp_seconds. Without a copy and without flags, the exporter has no providers and does
not start.
The exporter polls the providers every --interval (default 10m) and serves the cached values. /metrics serves the
metrics; /healthz returns 200 after the first poll. It needs read access to the state and to the management keys.
Key series have the labels name, team, kind, env, provider, service, owner, notify_channel,
alert_channel and reset, so Alertmanager can route by team and channel. orkeys has no alert thresholds: an alert
rule compares orkeys_key_spend_usd with orkeys_key_budget_usd, for example spend / budget > 0.8. For OpenAI keys
this rule is the only control of spend: OpenAI does not stop a key at its budget.
| Metric | Meaning |
|---|---|
orkeys_key_spend_usd |
Spend in the current limit period (reset: today, this week or this month) |
orkeys_key_budget_usd |
budget.limit from the manifest for the same period |
orkeys_key_hard_limit_usd |
Limit that the provider reports for the same period. A limit changed outside orkeys shows here, and differs from orkeys_key_budget_usd. No series for a key without a limit at the provider, and for providers without a per-key limit (OpenAI). A key missing at the provider shows budget.limit |
orkeys_key_usage_usd_total |
Counter of the key usage in USD, as the provider reports it. Use increase() or rate(). It resets at each rotation; DeepInfra and OpenAI also reset it at the start of each month. OpenAI data is hours late |
orkeys_key_expires_timestamp_seconds |
Expiry. Not for a tracked key without a provider expiry |
orkeys_key_last_used_timestamp_seconds |
Last use (OpenRouter and OpenAI). OpenRouter reports the request time for recently used keys, so treat it as "recently used", not as an exact time |
orkeys_key_created_timestamp_seconds |
Creation time of the key at the provider. When the provider does not report it: the time when orkeys created or adopted the key |
orkeys_key_rotation_state |
0 idle, 1 consumers not synced, 2 old key waits for revoke, 4 failed |
orkeys_key_pending_revoke_timestamp_seconds |
Earliest planned revoke time of an old key after a rotation. rotate holds the revoke while the old key is in use. A value far in the past means that a consumer still uses the old key |
orkeys_key_missing |
1 if the key is not found at the provider |
orkeys_key_disabled |
0 enabled, 1 disabled by the manifest (disabled: true), 2 disabled at the provider and not in the manifest. DeepInfra: a limit of 0 is disabled. No series for a missing key |
orkeys_key_track_only |
1 if the key has track_only: true: orkeys does not rotate it, and a person must renew it before orkeys_key_expires_timestamp_seconds. 0 for a managed key |
orkeys_unmanaged_keys{provider} |
Provider keys without state that the provider options do not ignore. Not exported with report_unmanaged: false. The exporter reads the options from --policy or from the copy in the state store |
orkeys_provider_poll_success{provider} |
1 if the last poll worked |
orkeys_provider_last_poll_timestamp_seconds{provider} |
Last successful poll |
orkeys_state_last_load_timestamp_seconds |
Last successful state load |
orkeys_policy_last_load_timestamp_seconds |
Last successful load of policy.yaml from the state store. Not exported with --policy. Alert when it is older than 30m |
orkeys_exporter_build_info{version} |
Always 1. version is the orkeys version of the exporter. CI and the exporter must read the same state and policy format, so compare it with the version in CI |
orkeys_last_success_timestamp_seconds{operation} |
Last successful apply, rotate, hygiene, request, revoke. Alert when rotate is older than 2h: without it, keys with a native expiry expire at the provider |
The exporter runs all the time with the management keys. Give it its own management keys where the provider allows it, and keep them in a secret that only the exporter reads.
The Dockerfile builds a distroless image with only the orkeys binary. It is enough for the exporter and for every
command except rotate with consumers, which runs kubectl. For rotate, run orkeys where kubectl and the cluster
contexts are available, for example in CI.
make # build ./orkeys
make check # gofmt check, go vet, tests (GOTEST_FLAGS=-race for the race detector)
make lint # golangci-lint
make vuln # govulncheck
make release # cross-compile into dist/
make snapshot # local GoReleaser build, no publish
make help # all targetsLayout:
| Path | Contents |
|---|---|
internal/openrouter |
HTTP client for the OpenRouter Management API |
internal/deepinfra |
HTTP client for DeepInfra API tokens and key limits |
internal/openai |
HTTP client for the OpenAI Admin API: project keys, service accounts, costs |
internal/httpx |
JSON over HTTP with retries for GET |
internal/nullable |
request fields that are absent, null or set |
internal/provider |
common interface, optional Limiter and Disabler, and registry of the providers |
internal/provider/providertest |
contract test that every provider adapter passes |
internal/manifest |
inventory loading and validation; consumer types in consumer.go |
internal/state, internal/secrets |
state and secret store interfaces |
internal/vault, internal/s3store, internal/awssm, internal/backend |
Vault KV v2, S3, Secrets Manager, and the factory that picks them |
internal/engine |
plan, apply, rotate, request, issued, revoke, state listing, hygiene, import; consumer drivers in consumers.go, recovery in recover.go |
internal/exporter |
Prometheus metrics |
internal/kube, internal/deliver, internal/github |
kubectl, age delivery, org membership, Actions secrets |
internal/cli |
cobra commands: openrouter.go, deepinfra.go, openai.go, keys.go, inventory.go, exporter_cmd.go; wiring in wire.go, output in render.go, event webhook in webhook.go, log setup in logging.go |
examples/inventory |
example inventory repository with rotate and hygiene workflows; a test keeps it valid |
internal/values |
input parsing and formatting |
- Add an HTTP client package (
internal/<name>) oninternal/httpx. - Add an adapter in
internal/providerthat implementsProvider. ImplementLimiteronly if the provider has a per-key limit, andDisableronly if it can disable keys. SetCapsto match:Newrefuses a mismatch. - Add an
Infotoregistry:Optionsfor settings beyondbase_urlandworkspace,CheckScopesfor scopes that orkeys must not request. - Add a fake of the API that keeps keys in memory, and run
providertest.Runagainst the adapter (seeinternal/provider/conformance_test.go). - Add the provider to the support tables of this README. A provider command (
orkeys <name> ...) is optional:orkeys keys -p <name>works without one.
- Add a spec type in
internal/manifest/consumer.gowithyamltags and aValidatemethod, and add it toconsumerTypes. A spec that orkeys writes the key to implementsPushSpec(TargetID); a spec that reads the secrets store implementsNotifySpec(Workloads). - Add a driver in
internal/enginethat implementsPusherorNotifier, and register it ininternal/cli/wire.go. Push targets are recorded in the state under<type>/<target ID>, so orkeys can delete them after the manifest is gone. - Add a row to the key manifest table of this README.
- Bump
VERSIONwithmake bump-patch,make bump-minorormake bump-major. - Add a
## vX.Y.Z (YYYY-MM-DD)section toCHANGELOG.mdwith the changes and their commits. - Merge to
main. The Release workflow tags the commit with the content ofVERSION, builds the binaries and creates the GitHub release.