Least-privilege API keys for DeepSeek Harness
The test for a least-privilege key is one sentence: it can list models, send conversations, and read the data its owner needs — and cannot perform any management action. Every extra permission becomes extra incident cost when it leaks.
One principle for least-privilege API keys
What a key can do is decided when it is issued, not by the client using it. Two keys look identical in the same interface and behave completely differently.
So define the purpose first, then request the key. Issue keys before the purpose is clear and you will grant broadly "to save time", then never claw it back.
API key boundaries by user type: people, CI, plugins
Classifying by user works better than classifying by feature.
| User | Needs | Must not have |
|---|---|---|
| Individual developer | List models, converse | Member management, billing edits |
| CI or scripts | List models, converse | Console operations, member management |
| Balance or billing plugin | Read-only quota or usage | Conversations, member management |
Plugins are the most over-granted. A widget that only renders a number often receives the main key, which makes a leak equivalent to leaking the account.
Individuals: one key per person
Per-person keys are the starting point for isolation.
- One key each, named with initials or an employee ID;
- Grant only model listing and conversation;
- Issue on joining, revoke on leaving, as a fixed routine;
- Never share or lend, so an incident maps to a person;
- Periodically reconcile active keys against the member list.
Per-person does not mean per-person trust. Its value is surgical revocation, not stronger security.
CI and scripts: one key per environment
CI keys belong to tasks, not people.
- They run fixed pipelines, so scope can be minimal;
- They have a known time window and quota ceiling;
- A leak can be revoked without touching developers;
- Keys never appear in logs or build output;
- Revoke after use, or rotate on a schedule.
The dominant CI risk is a key baked into a cache or image layer. Once it is in a layer, revoking the key does not erase history; the artifact must be rebuilt.
Plugins: one read-only key
Scope a plugin by what it displays.
- Balance plugins need quota queries, not conversations;
- Billing plugins need usage reads, not writes;
- Issue a dedicated key named after the plugin;
- For an unverified plugin, withhold the key or test it in isolation;
- Revoke the key when the plugin is removed.
A plugin is third-party code and should be treated as such. You do not control its updates, so read-only today does not guarantee read-only next version.
What never goes on a normal API key
Three scopes should never appear on an ordinary key.
- Member and account management: a key that can change permissions can escalate;
- Billing and top-up: changing a bill is worse than spending quota;
- Delete and reset operations: mistakes and malice are both irreversible.
The test: could this action be undone if it went wrong? If not, it does not belong on a normal key.
Verifying an API key is just enough
Verify with a minimal flow, not a feature checklist.
- List available models with the key and confirm success;
- Send the shortest possible message and confirm output;
- Query the quota or usage this key is meant to read, if it is a plugin key;
- Attempt an administrative action it should not allow and confirm rejection;
- Record the results as this key's permission statement.
Step four is the important one. Proving that something works is not enough; you also need proof that the things which should fail do fail.
API key distribution and blast radius
Smaller scope makes a leak easier to handle.
- A main key leaks: stop all calls, inspect every environment, notify every user;
- A read-only plugin key leaks: revoke one, leave everything else running.
Distribute only the key that is needed. Copying the main key to everyone with a verbal "be careful" does not prevent mistakes.
Be stricter on shared machines. When several people use one environment, key visibility needs its own design; see dsh multi-user and LAN.
Next steps: fix the API key scope before rotation
Fix the scope before discussing rotation. For the full lifecycle, read API key lifecycle. For key errors, read API key error troubleshooting. For balance plugins, read balance and usage plugins.
Sources: DeepSeek API docs, DeepSeek Harness docs, dsh CLI README
FAQ
A normal DeepSeek Harness API key should list models, send conversations, and read only the quota or usage its owner actually needs. It should not manage members, change billing, or perform destructive operations. Scope is decided at issue time, not by the client.
Sharing one main API key is a bad idea because a leak cannot be contained. Revoking it stops everyone at once, and you cannot tell which person or machine caused the exposure. One key per person keeps revocation surgical.
A balance plugin should get read-only quota access, issued as its own API key. A display widget does not need conversation rights, and giving it the main key makes a third-party plugin as powerful as your account.
Test both directions with the API key: confirm a model list and a short message succeed, then attempt an administrative action it should not allow and confirm rejection. Recording both results is the permission statement for that key.
Related Terms
- least privilege
- Least privilege is the practice of issuing a credential with only the capabilities its task requires, so a leak has a bounded blast radius.— DeepSeek API docs
- scope
- A scope is the set of actions a credential is permitted to perform, fixed when the credential is issued rather than chosen by the client at runtime.— DeepSeek API docs
- read-only key
- A read-only key is one that can query balances or usage but cannot send conversations or modify account settings, making it safe for dashboard plugins.— DeepSeek Harness docs
- build artifact
- A build artifact is output produced by CI, such as an image layer or bundle; a key embedded there survives revocation until the artifact is rebuilt.— dsh CLI README
Sources
- DeepSeek API docs· DeepSeek
- DeepSeek Harness docs· deepseek-harness
- dsh CLI README· deepseek-ai