Keep the personal half of the desktop in one place, and ask before installing it
Agent instructions, skills, SSH host aliases and expansion triggers are worth having identical on every machine one person owns, and belong in none of the shared configuration. They live in user/ now, with a manifest saying where each piece goes and a link-user stage that puts it there. That stage does nothing unless the machine said yes. Somebody who clones Panama to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was; the question names the destinations and defaults to no. Anything displaced goes to config/old rather than being deleted. ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one file, which is the drift this exists to prevent. Also adds the vitals toggles for the battery and Claude usage readouts, which had preferences and no way to reach them.
This commit is contained in:
Gabriel Brown
@@ -0,0 +1,338 @@
|
||||
# Secrets Endpoints
|
||||
|
||||
All secret operations use `/api/v4/secrets`. Previous API versions (v1, v2, v3) are deprecated.
|
||||
|
||||
## List Secrets
|
||||
|
||||
### Endpoint
|
||||
|
||||
```
|
||||
GET /api/v4/secrets
|
||||
```
|
||||
|
||||
### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Max | Description |
|
||||
|-----------|------|----------|---------|-----|-------------|
|
||||
| projectId | string | Yes | - | - | ID of the project |
|
||||
| environment | string | Yes | - | - | Environment slug (e.g., "dev", "prod") |
|
||||
| secretPath | string | No | "/" | - | Secret folder path (e.g., "/database", "/") |
|
||||
| offset | integer | No | 0 | - | Number of items to skip for pagination |
|
||||
| limit | integer | No | 20 | 100 | Number of items to return per page |
|
||||
| viewSecretValue | boolean | No | false | - | Include plaintext secret values in response |
|
||||
| expandSecretReferences | boolean | No | false | - | Expand secret references (e.g., `${OTHER_SECRET}`) |
|
||||
| recursive | boolean | No | false | - | Include secrets from all subdirectories |
|
||||
| includeImports | boolean | No | false | - | Include secrets from imported secret environments |
|
||||
| tagSlugs | string | No | - | - | Comma-separated tag slugs to filter by |
|
||||
| metadataFilter | string | No | - | - | JSON filter for metadata-based search |
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"secrets": [
|
||||
{
|
||||
"id": "secret-id-uuid",
|
||||
"version": 1,
|
||||
"workspace": "workspace-id",
|
||||
"project": "project-id",
|
||||
"environment": "dev",
|
||||
"secretPath": "/",
|
||||
"secretName": "DATABASE_URL",
|
||||
"secretValue": "postgres://user:pass@localhost/db",
|
||||
"secretComment": "Production database connection",
|
||||
"type": "shared",
|
||||
"tags": [
|
||||
{
|
||||
"id": "tag-id",
|
||||
"slug": "database",
|
||||
"name": "Database",
|
||||
"color": "#3b82f6"
|
||||
}
|
||||
],
|
||||
"createdAt": "2026-04-16T10:30:00.000Z",
|
||||
"updatedAt": "2026-04-16T10:30:00.000Z",
|
||||
"createdBy": "user-id"
|
||||
}
|
||||
],
|
||||
"total": 42,
|
||||
"offset": 0,
|
||||
"limit": 20
|
||||
}
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X GET 'https://us.infisical.com/api/v4/secrets?projectId=abc123&environment=dev&offset=0&limit=20&viewSecretValue=true' \
|
||||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
||||
```
|
||||
|
||||
## Get Secret
|
||||
|
||||
### Endpoint
|
||||
|
||||
```
|
||||
GET /api/v4/secrets/{secretName}
|
||||
```
|
||||
|
||||
### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Default | Description |
|
||||
|-----------|------|----------|---------|-------------|
|
||||
| projectId | string | Yes | - | ID of the project |
|
||||
| environment | string | Yes | - | Environment slug |
|
||||
| secretPath | string | No | "/" | Secret folder path |
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"secret": {
|
||||
"id": "secret-id-uuid",
|
||||
"version": 1,
|
||||
"workspace": "workspace-id",
|
||||
"project": "project-id",
|
||||
"environment": "dev",
|
||||
"secretPath": "/",
|
||||
"secretName": "API_KEY",
|
||||
"secretValue": "sk_live_abc123def456ghi789",
|
||||
"secretComment": "Third-party API key",
|
||||
"type": "shared",
|
||||
"tags": [],
|
||||
"createdAt": "2026-04-16T10:30:00.000Z",
|
||||
"updatedAt": "2026-04-16T10:30:00.000Z",
|
||||
"createdBy": "user-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X GET 'https://us.infisical.com/api/v4/secrets/API_KEY?projectId=abc123&environment=dev&secretPath=/' \
|
||||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
||||
```
|
||||
|
||||
## Create Secret
|
||||
|
||||
### Endpoint
|
||||
|
||||
```
|
||||
POST /api/v4/secrets/{secretName}
|
||||
```
|
||||
|
||||
### Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| projectId | string | Yes | ID of the project |
|
||||
| environment | string | Yes | Environment slug |
|
||||
| secretPath | string | No | Secret folder path (default: "/") |
|
||||
| secretValue | string | Yes | The secret value (plaintext) |
|
||||
| type | string | No | "shared" or "personal" (default: "shared") |
|
||||
| tagIds | array | No | List of tag IDs to attach |
|
||||
| secretComment | string | No | Comment/description for the secret |
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"secret": {
|
||||
"id": "secret-id-uuid",
|
||||
"version": 1,
|
||||
"workspace": "workspace-id",
|
||||
"project": "project-id",
|
||||
"environment": "dev",
|
||||
"secretPath": "/",
|
||||
"secretName": "NEW_SECRET",
|
||||
"secretValue": "super-secret-value",
|
||||
"secretComment": "My new secret",
|
||||
"type": "shared",
|
||||
"tags": [],
|
||||
"createdAt": "2026-04-16T10:30:00.000Z",
|
||||
"updatedAt": "2026-04-16T10:30:00.000Z",
|
||||
"createdBy": "user-id"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X POST 'https://us.infisical.com/api/v4/secrets/DATABASE_PASSWORD' \
|
||||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"projectId": "abc123",
|
||||
"environment": "dev",
|
||||
"secretPath": "/",
|
||||
"secretValue": "my-secure-password",
|
||||
"type": "shared",
|
||||
"secretComment": "Database password for dev environment"
|
||||
}'
|
||||
```
|
||||
|
||||
## Update Secret
|
||||
|
||||
### Endpoint
|
||||
|
||||
```
|
||||
PATCH /api/v4/secrets/{secretName}
|
||||
```
|
||||
|
||||
### Request Body
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|-------|------|----------|-------------|
|
||||
| projectId | string | Yes | ID of the project |
|
||||
| environment | string | Yes | Environment slug |
|
||||
| secretPath | string | No | Secret folder path |
|
||||
| secretValue | string | No | New secret value |
|
||||
| secretComment | string | No | Updated comment/description |
|
||||
| tagIds | array | No | Updated list of tag IDs |
|
||||
|
||||
### Response
|
||||
|
||||
Same as Create Secret response.
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X PATCH 'https://us.infisical.com/api/v4/secrets/DATABASE_PASSWORD' \
|
||||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"projectId": "abc123",
|
||||
"environment": "dev",
|
||||
"secretPath": "/",
|
||||
"secretValue": "new-secure-password"
|
||||
}'
|
||||
```
|
||||
|
||||
## Delete Secret
|
||||
|
||||
### Endpoint
|
||||
|
||||
```
|
||||
DELETE /api/v4/secrets/{secretName}
|
||||
```
|
||||
|
||||
### Query Parameters
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|-----------|------|----------|-------------|
|
||||
| projectId | string | Yes | ID of the project |
|
||||
| environment | string | Yes | Environment slug |
|
||||
| secretPath | string | No | Secret folder path (default: "/") |
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"secret": {
|
||||
"id": "secret-id-uuid",
|
||||
"secretName": "DELETED_SECRET"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X DELETE 'https://us.infisical.com/api/v4/secrets/OLD_SECRET?projectId=abc123&environment=dev&secretPath=/' \
|
||||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
|
||||
```
|
||||
|
||||
## Batch Delete Secrets
|
||||
|
||||
### Endpoint
|
||||
|
||||
```
|
||||
DELETE /api/v4/secrets/batch
|
||||
```
|
||||
|
||||
### Request Body
|
||||
|
||||
```json
|
||||
{
|
||||
"projectId": "string",
|
||||
"environment": "string",
|
||||
"secretPath": "string",
|
||||
"secretIds": ["uuid1", "uuid2", "uuid3"]
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"deletedSecrets": [
|
||||
{
|
||||
"id": "uuid1",
|
||||
"secretName": "SECRET_1"
|
||||
},
|
||||
{
|
||||
"id": "uuid2",
|
||||
"secretName": "SECRET_2"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```bash
|
||||
curl -X DELETE 'https://us.infisical.com/api/v4/secrets/batch' \
|
||||
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"projectId": "abc123",
|
||||
"environment": "dev",
|
||||
"secretPath": "/",
|
||||
"secretIds": ["id1-uuid", "id2-uuid"]
|
||||
}'
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
### API Version
|
||||
|
||||
- Use `/api/v4/secrets` for all new code
|
||||
- `/api/v1/secrets`, `/api/v2/secrets`, and `/api/v3/secrets` are deprecated
|
||||
- Migrate existing integrations to v4 endpoints
|
||||
|
||||
### Secret Names
|
||||
|
||||
- Must be unique within the environment and secret path
|
||||
- Use uppercase with underscores (e.g., `DATABASE_PASSWORD`)
|
||||
- Cannot contain spaces or special characters
|
||||
|
||||
### Secret Types
|
||||
|
||||
- **shared**: Visible to all project members with appropriate permissions
|
||||
- **personal**: Only visible to the user who created it
|
||||
|
||||
### Secret Values
|
||||
|
||||
- Plaintext strings only
|
||||
- For large values, base64-encode before creating
|
||||
- References using `${SECRET_NAME}` syntax are supported when `expandSecretReferences=true`
|
||||
|
||||
### Tags
|
||||
|
||||
- Secrets can have multiple tags
|
||||
- Tags are organization-wide but applied per secret
|
||||
- Use `tagSlugs` parameter to filter list results by tag
|
||||
|
||||
### Pagination
|
||||
|
||||
- Always specify `offset` and `limit` for predictable results
|
||||
- Default limit is 20; maximum is 100
|
||||
- Use `total` to determine remaining items: `hasMore = (offset + limit) < total`
|
||||
|
||||
### Performance
|
||||
|
||||
- For listing many secrets (>1000), use pagination with `limit=100`
|
||||
- Avoid `viewSecretValue=true` on large lists unless values are needed
|
||||
- Use `recursive=false` by default for better performance
|
||||
Reference in New Issue
Block a user