vault-api

Files (2)

• LICENSE
• SKILL.md

SKILL.md (first lines)

# Vault API

## Overview

Vault exposes a RESTful JSON API on port 8200. All requests include `X-Vault-Token` header for authenticated endpoints. Unauthenticated endpoints (health, init) need no token.

**Base URL:** `http://vault.vault:8200` (in-cluster) or `https://vault.kubexa.tech` (external via Gateway).

## API Endpoints

### System

| Method | Endpoint | Description | Auth |
|--------|----------|-------------|------|
| `GET` | `/v1/sys/health` | Cluster health (see status codes below) | No |
| `GET` | `/v1/sys/seal-status` | Seal status | No |
| `PUT` | `/v1/sys/init` | Initialize cluster | No |
| `PUT` | `/v1/sys/unseal` | Unseal (submit key share) | No |
| `GET` | `/v1/sys/leader` | Current leader info | No |

**Health status codes:**

| Code | Meaning |
|------|---------|
| `200` | Active, unsealed |
| `429` | Standby, unsealed |
| `472` | Disaster Recovery secondary (enterprise) |
| `473` | Performance standby (enterprise) |
| `501` | Not initialized |
| `503` | Sealed |

### Auth (Kubernetes)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/v1/auth/kubernetes/login` | Login with service account JWT |

```bash
# Login with K8s SA token
SA_JWT=$(kubectl create token my-sa -n my-ns)
curl -s http://vault.vault:8200/v1/auth/kubernetes/login \
  -d "{\"role\":\"my-role\",\"jwt\":\"$SA_JWT\"}"
# Returns: {"auth":{"client_token":"hvs...","policies":["my-policy"]}}
```

### KV Secrets (v2)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/{mount}/data/{path}` | Read secret |
| `PUT` | `/v1/{mount}/data/{path}` | Create/update secret |
| `DELETE` | `/v1/{mount}/data/{path}` | Delete latest version |
| `GET` | `/v1/{mount}/metadata/{path}` | Read metadata (versions, timestamps) |
| `POST` | `/v1/{mount}/delete/{path}` | Delete all versions |
| `POST` | `/v1/{mount}/undelete/{path}` | Undelete |

```bash
# Write a secret
curl -s http://vault.vault:8200/v1/secret/data/myapp \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -d '{"data":{"password":"s3cret!"}}'

# Read a secret
curl -s http://vault.vault:8200/v1/secret/data/myapp \
  -H "X-Vault-Token: $VAULT_TOKEN"
# Returns: {"data":{"data":{"password":"s3cret!"},"metadata":{...}}}

# List secrets at a path
curl -s http://vault.vault:8200/v1/secret/metadata/myapp \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  | jq '.data.keys'
```

### KV Secrets (v1)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/{mount}/{path}` | Read secret |
| `PUT` | `/v1/{mount}/{path}` | Create/update secret |
| `DELETE` | `/v1/{mount}/{path}` | Delete secret |

### Policies

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/sys/policies/acl` | List ACL policies |
| `GET` | `/v1/sys/policies/acl/{name}` | Read policy |
| `PUT` | `/v1/sys/policies/acl/{name}` | Create/update policy |
| `DELETE` | `/v1/sys/policies/acl/{name}` | Delete policy |

```bash
# Create read-only policy for myapp
curl -s http://vault.vault:8200/v1/sys/policies/acl/myapp \
  -X PUT \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -d '{"policy":"path \"secret/data/myapp/*\" {capabilities=[\"read\",\"list\"]}"}'
```

### Token

| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/v1/auth/token/create` | Create token |
| `POST` | `/v1/auth/token/create-orphan` | Create orphan token |
| `GET` | `/v1/auth/token/lookup-self` | Validate/lookup own token |
| `POST` | `/v1/auth/token/renew-self` | Renew own token |
| `POST` | `/v1/auth/token/revoke-self` | Revoke own token |

### Auth Methods

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/sys/auth` | List enabled auth methods |
| `POST` | `/v1/sys/auth/{type}` | Enable auth method |
| `DELETE` | `/v1/sys/auth/{path}` | Disable auth method |

### Secrets Engines

| Method | Endpoint | Description |

From Kilo-Org/kilo-marketplace, Apache-2.0.

More from Kilo-Org/kilo-marketplace