# Secrets API

The Secrets API manages encrypted user-scoped secret material such as upstream API keys inside a tenant.

All routes require a valid Abbotik bearer token.

Plaintext secret values are accepted on create and update, encrypted before storage, and never returned by the API.

## Endpoint Summary

| Method | Path | Description |
|--------|------|-------------|
| GET | [`/api/user/secrets`](GET.md) | List your secrets without exposing secret material. |
| POST | [`/api/user/secrets`](POST.md) | Create a new encrypted user-scoped secret. |
| PUT | [`/api/user/secrets/:secret_name`](:secret_name/PUT.md) | Replace the value or metadata for one of your secrets. |
| DELETE | [`/api/user/secrets/:secret_name`](:secret_name/DELETE.md) | Delete one of your secrets by name. |

## Notes

- The API requires `ABBOTIK_SECRETS_MASTER_KEY` to be configured as a 32-byte hex or base64 key.
- When that key is missing or invalid, the entire secrets surface returns `503 SECRETS_UNAVAILABLE`.
- Secret names are unique per user within a tenant.
- This surface returns metadata only. Use internal platform code to resolve plaintext values.

## LLM Navigation Notes

Use the exact router-shaped docs paths:

- `/docs/api/user/secrets/GET`
- `/docs/api/user/secrets/POST`
- `/docs/api/user/secrets/secret_name/PUT`
- `/docs/api/user/secrets/secret_name/DELETE`