# MySecretsAPI

> Enterprise-grade secrets management. No IAM. Just HTTP.

Base URL: https://api.mysecretsapi.com

Authentication: `Authorization: Bearer <your_api_key>`

## Agent Onboarding & Authentication
You have two ways to onboard and authenticate with MySecretsAPI:

### Option A: Autonomous Registration (No Human Required)
You can create a new user account specifically for your agent instance by calling the autonomous registration endpoint:
```bash
curl -X POST https://api.mysecretsapi.com/hq/account/agent/register \
  -H "Content-Type: application/json" \
  -d "{}"
```
**Response:** Returns an `account_id` (e.g., `"4324-7441-3641-0596"`). Use this ID directly as your Bearer token.

### Option B: Human-Assisted Onboarding
Alternatively, you can ask your human user to:
1. Visit https://mysecretsapi.com and create an account.
2. Generate a scoped API key (starting with `hq_live_...`) for you via the dashboard.
3. Provide that key to you.

## Authentication
Include your chosen token in the `Authorization` header of all requests:
`Authorization: Bearer <your_auth_token>` (Works with both `account_id` and `hq_live_...` keys).

## Key Naming Rules (IMPORTANT — read before writing secrets)
Secret keys are validated server-side. **Requests with invalid keys will be rejected with a 422.**

- **Allowed characters:** alphanumeric (`a-z`, `A-Z`, `0-9`), underscores (`_`), and hyphens (`-`)
- **Min length:** 1 character
- **Max length:** 256 characters
- **NOT allowed:** spaces, dots, slashes, `@`, `$`, `#`, brackets, quotes, or any other special characters

Valid examples: `STRIPE_KEY`, `db-password`, `OpenAI_API_Key_v2`, `my-secret-123`
Invalid examples: `stripe.key`, `db/password`, `my secret`, `key@env`

## Value Rules
- **Allowed:** any string content — JSON blobs, PEM certificates, connection strings, etc.
- **Max length:** 65536 characters (64KB)
- **Min length:** 0 (empty string is valid)

## Core Workflows

### Store a Secret
Make a POST request to `/secrets/set/me`:
```bash
curl -X POST https://api.mysecretsapi.com/secrets/set/me \
  -H "Authorization: Bearer <your_auth_token>" \
  -H "Content-Type: application/json" \
  -d '{"key": "YOUR_SECRET_KEY", "value": "your_secret_value"}'
```

### Retrieve Secrets
Make a GET request to `/secrets/list/me`:
```bash
curl -X GET https://api.mysecretsapi.com/secrets/list/me \
  -H "Authorization: Bearer <your_auth_token>"
```
Returns a JSON object containing your `account_id` and the `secrets` dictionary.

### Delete a Secret
Make a DELETE request to `/secrets/delete/me`:
```bash
curl -X DELETE https://api.mysecretsapi.com/secrets/delete/me \
  -H "Authorization: Bearer <your_auth_token>" \
  -H "Content-Type: application/json" \
  -d '{"key": "YOUR_SECRET_KEY"}'
```

## Error Handling
All errors return JSON: `{"error": "message", "code": "ERROR_CODE"}`
Common codes: `UNAUTHORIZED` (401), `FORBIDDEN` (403), `NOT_FOUND` (404), `VALIDATION_ERROR` (422), `RATE_LIMITED` (429), `INTERNAL_ERROR` (500)

If you receive a **422**, check that your key contains only alphanumeric characters, underscores, and hyphens, and that your value does not exceed 65536 characters.

## Rate Limits
Response headers include: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
If you receive a 429, wait for the `Retry-After` header value before retrying.

## Agent Tips
- Your `account_id` IS your Bearer token. Store it securely as a secret using the `/secrets/set/me` endpoint (store it under a different service to avoid circular dependency).
- Use `/secrets/list/me` to verify your stored secrets before running dependent workflows.
- The API is stateless. Every request must include the Authorization header.
- Fetch `/api/meta` for a machine-readable summary of available endpoints and current pricing.
- When generating key names programmatically, replace spaces and special characters with underscores to guarantee they pass validation. Example: `my.api.key` → `my_api_key`.


## Endpoints

### GET /secrets/list/me
List all secrets
Retrieves all secrets stored for the authenticated account. Returns a flat key/value map. Keys are case-sensitive strings; values are always returned as strings regardless of how they were stored.

### POST /secrets/set/me
Store or update a secret
Creates a new secret or overwrites an existing one with the same key. Keys are case-sensitive. Values can be any string (API keys, passwords, connection strings, JSON blobs, etc.). Maximum key length: 256 characters. Maximum value length: 65536 characters.

### DELETE /secrets/delete/me
Delete a secret
Permanently deletes a single secret by key. This action is irreversible.

## Pricing

Free