Person and service keys#

In team mode every call carries a Lockpin key (lp_...) instead of a provider key. This page covers the two kinds of key, their limits, how long they live and what each may use. It is for the admins and team leads who make and manage keys.

Two kinds of key#

Kind	For	Lives	At a task’s budget
Person	One developer or one agent a person runs	180 days	Asks whoever watches the meter (`-task-cap ask`), or refuses with `-task-cap hard`
Service	One automated job: a CI job, a cron agent	90 days	Always refuses, asking no one

Because jobs do not use people’s keys, disabling one person’s key when they leave stops no job.

Service keys#

A service key is a job’s own long-lived identity. Make one with -service:

lockpin keys create svc.eng.ci-review.prod -service -team eng -day 50 -task 8

Its name is svc.TEAM.JOB or svc.TEAM.JOB.ENV, and -team is required.
It is always a member. It never administers and never answers held calls.
Every call must name its run in X-Lockpin-Task, else it gets 400 task_required.
A run that would pass its task budget is refused with no one asked.
A service key is always refused on the admin page.

For one run that needs a short-lived slice of a budget, a node can hand out a spend capability (lpc_...) instead. See Run a team node.

Before you begin#

A team server is set up and running with a keys file. See Set up a team.
You run lockpin keys on the server, against the same keys file (-file, default lockpin-keys.json).

Make and hand out a key#

Make the key with its limits:
```
lockpin keys create alice -team eng -day 40
```
It prints the key and the date it expires. The secret is shown only this once.
Give the key to its holder. They set it as their client’s API key, with the server’s base URL. See Connect an agent.
Check it:
```
lockpin keys list
```

A running Lockpin picks up changes to the keys file within a second, with no restart. To skip handing out secrets, send an invite instead: it makes one key when someone opens it.

Limits#

Limits are in USD per UTC calendar day, week (from Monday), month, or in total (never resets), in any mix. A call reserves its worst case against the task’s budget and every limit of its key at once, so a key stops exactly at its limit, even with many calls in flight. The 402 says which limit was hit and when it resets.

Flag	What it does
`-day`, `-week`, `-month`, `-total`	Limit in USD per day, week, month, or in total.
`-user-day`	USD per day for each user of the key, named by `X-Lockpin-User`. The key then requires that header.
`-tag NAME=VALUE`	Added to every call made with the key. Repeat it for more.
`-task`	USD each new task of the key starts with. Default: `-default-budget`.
`-task-cap`	`ask` or `hard`, at a task’s budget. Service keys are always `hard`.
`-team`, `-role`	The key’s team, and its role: `owner`, `admin`, `lead` or `member`.

Key, team and day limits refuse in every mode. Only the task budget can ask.

lockpin keys create support-bot -day 50 -user-day 2
lockpin keys set alice -day 60

lockpin keys set changes only the limits you give, and 0 removes one. Spend so far still counts after a limit changes. -tag team=backend sets a tag and -tag team= removes it.

Note

A key’s X-Lockpin-Budget-Usd header can only lower its task’s budget, never raise it or remove the cap. A higher value is ignored. Budgets set in the meter stay as the admin set them.

Team member defaults#

A team’s member default holds each person’s key in the team to the lower of the default and the key’s own limit. lockpin keys list marks such a limit with *, and a 402 at it names the team default. Service keys keep their own limits. See Teams and member defaults.

Allowed AI#

A key can be limited to some providers, and to models that match patterns where * is any run of characters:

lockpin keys create alice -providers openai,anthropic -models 'gpt-*-mini'
lockpin keys set alice -providers ''

An empty value allows all again. A call outside them gets 403 (provider_not_allowed or model_not_allowed) saying what the key may use, and nothing is charged. A key cannot allow more than its team, and a team cannot allow more than the workspace. You can also use Edit under Allowed AI in the meter’s Keys panel. Members see what they may use, and the base URLs for it, on /lockpin/me.

Key lifetimes#

A person’s key lives 180 days and a service key 90, unless -expires or lockpin keys lifetime says otherwise. A key made from an invite lives 180 days too.

`-expires` value	Meaning
`Nd`	That many days from now, such as `30d`.
`YYYY-MM-DD`	That date, in UTC.
`never`	No end of its own. A maximum set with `lifetime` still applies.

-expires is at most ten years away.

lockpin keys create bob -expires 30d
lockpin keys lifetime -max-days 365

lockpin keys lifetime shows or sets how long keys live:

-max-days N ends every key at most N days after its secret was made. Keys made before it count from the day it is set. A maximum that would end keys at once is refused unless you add -force, which gives them 14 days, with the warnings.
-person-days N and -service-days N set new keys’ lifetimes. 0 means no end of their own.
A maximum never ends the key lockpin init or lockpin node install made.

Lockpin warns 14 and 3 days before a key expires, and when it has (alerts key_expiring and key_expired), in the meter, the member page, VS Code and the alert destinations. An expired key’s calls are refused with 401 key_expired, naming the command that renews it. lockpin keys list ends with a line naming the keys that expire within 14 days.

Rotate, disable and enable#

Command	What it does
`lockpin keys rotate NAME`	A new secret and a fresh lifetime as long as before, with the same name, limits, team, role and spend history. The old secret stops working. An expired key comes back this way.
`lockpin keys disable NAME`	Stop a key at once.
`lockpin keys enable NAME`	Let a disabled key work again.

The keys file holds only hashes of the keys, so a lost secret means lockpin keys rotate, not recovery.

What a key holder sees#

Reply headers. Each reply carries X-Lockpin-Key-Remaining-Usd (what is left under the tightest limit), X-Lockpin-Key-Resets and, for a key with an end, X-Lockpin-Key-Expires (RFC 3339).
The member page. /lockpin/me on the server’s address shows the holder’s own spend, limits, allowed AI, base URLs and team lead.
VS Code. With extension 0.1.5 or later, Lockpin: Set my Lockpin key keeps the key in VS Code’s secret storage and shows it under Me in the Overview. Lockpin: Forget my Lockpin key removes it. See VS Code extension.
Tasks are kept apart per key. Alice’s fix-tests is alice/fix-tests in the meter.

Honest limits#

Calls Lockpin cannot meter (embeddings, files, batches) could spend uncapped, so team mode refuses them with 403. Other reads (files, stored responses, batch output) are refused too, since everyone shares the team’s provider key. The model list (GET /models) and the free input-token count still pass.
Tag and user limits are only as good as the names calls carry. An agent can pick its tags unless the key’s tags are locked with -tags-locked.

Verify#

List the keys, their kind, when each expires, and spend against limits:
```
lockpin keys list
```
Make one call with the key and check the reply’s X-Lockpin-Key-Remaining-Usd header.