> For the complete documentation index, see [llms.txt](https://vampauth.gitbook.io/vampauth-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vampauth.gitbook.io/vampauth-docs/api-reference/management/keys.md).

# Keys

Paths are relative to `/api/v2`. Use project/key UUIDs. Plaintext keys belong in request bodies, never URLs.

| Method and path                                         | Scope            | Capability                                   |
| ------------------------------------------------------- | ---------------- | -------------------------------------------- |
| GET /keys                                               | keys:read        | view\_keys across allowed projects           |
| GET /projects/{project\_id}/keys                        | keys:read        | view\_keys                                   |
| POST /projects/{project\_id}/keys/lookup                | keys:read        | view\_keys; read-only POST                   |
| POST /projects/{project\_id}/keys                       | keys:write       | create\_keys                                 |
| POST /projects/{project\_id}/keys/batch                 | keys:write       | create\_keys                                 |
| POST /projects/{project\_id}/keys/bulk                  | action-dependent | edit\_keys, or delete\_keys for delete       |
| GET /projects/{project\_id}/keys/{key\_id}              | keys:read        | view\_keys                                   |
| PATCH /projects/{project\_id}/keys/{key\_id}            | keys:write       | edit\_keys; reset\_hwids too for binding/FFA |
| DELETE /projects/{project\_id}/keys/{key\_id}           | keys:delete      | delete\_keys                                 |
| POST /projects/{project\_id}/keys/{key\_id}/ban         | keys:write       | edit\_keys                                   |
| POST /projects/{project\_id}/keys/{key\_id}/unban       | keys:write       | edit\_keys                                   |
| POST /projects/{project\_id}/keys/{key\_id}/renew       | keys:write       | edit\_keys                                   |
| POST /projects/{project\_id}/keys/{key\_id}/reset-hwid  | keys:write       | reset\_hwids                                 |
| GET /projects/{project\_id}/keys/{key\_id}/fingerprints | keys:read        | view\_keys                                   |

## List and lookup

Lists accept limit/cursor and optional status (active/expired/banned/revoked), group\_id (UUID or ungrouped), bound (bound/unbound), case-insensitive alias, created\_after, and created\_before. The account list also accepts project\_id. Creation ranges must increase; unknown/duplicate query fields fail.

Lookup body: `{"key":"EXACT-KEY-VALUE"}`, 3–64 characters, body limit 1 KiB. It doesn't activate stock, mutate usage, or need Idempotency-Key.

## Create one or a batch

Optional fields: alias (up to 50 characters or null), duration\_seconds (60–31536000), expiry\_type (from\_first\_use/from\_creation), expires\_at (ISO timestamp/null), ffa (boolean), group\_id (same-project UUID/null). Single creation also accepts custom\_key (3–64 characters). Batch requires count (1–500) and generates its key values.

Don't combine duration\_seconds with expires\_at, or from\_first\_use with absolute expiry. Duration/default-based manual creation starts on first use unless overridden. Explicit expires\_at:null is lifetime. Both creation forms require Idempotency-Key and return 201.

```json
{ "alias": "Reseller stock", "expiry_type": "from_first_use", "duration_seconds": 86400 }
```

## Patch

Accepts alias, expires\_at, duration\_seconds, expiry\_type, hwid (up to 256 characters/null), ffa, group\_id. At least one field. Optional idempotency key; no If-Match requirement for key edits. Omit expiry fields to preserve the timer. Duration/start-type edits are for unused keys only.

## Lifecycle actions

Ban, unban, reset and delete accept empty input/{}. Renew requires `{"duration_seconds":3600}`. Renewal and reset require Idempotency-Key; other actions accept an optional key.

Pending renewal adds duration without activation. Active/fixed renewal extends max(database now, expiry). Lifetime/banned/revoked renewal conflicts. V2 unban explicitly restores active/expired from banned/revoked. Reset requires an existing binding and a non-banned/non-revoked state, preserves timer/history/usage, and invalidates leases.

## Bulk

Required: action and 1–500 distinct IDs from one project. Actions: delete, rename (+alias), renew (+duration\_seconds), ban, unban, set\_group (+group\_id), clear\_group. Atomic; returns affected\_count. Delete requires keys:delete/delete\_keys; other actions require keys:write/edit\_keys. Only renew requires Idempotency-Key, though other actions accept one.

## Response fields

id, project\_id, key, alias, status, expires\_at, group\_id, hwid, expiry\_type, duration\_seconds, activated\_at, ffa, fingerprint, stats, stack\_count, last\_stacked\_at, origin\_provider\_id, origin\_package\_id, origin\_expiry\_seconds, created\_at, updated\_at.

Stats include activations, executions, hwid\_resets, first\_used, last\_used, last\_executor. Null expiry alone doesn't mean lifetime: check first-use metadata. Fingerprint list entries contain observation hashes/context, accepted/denied outcome, counts, and first/last seen timestamps; they are advisory, not identity proof.

## Next steps

* [Keys and expiry](/vampauth-docs/features/keys-and-expiry.md)
* [Management API recipes](/vampauth-docs/development/management-recipes.md)
* [Management API errors](/vampauth-docs/troubleshooting/api-errors.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://vampauth.gitbook.io/vampauth-docs/api-reference/management/keys.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.