Vault API

Base URL: https://api.sparbz.cloud/api/v1

Overview

The Vault API provides secret management, encryption, and access control. Store sensitive data securely, manage encryption keys, set policies for access control, and audit all operations.

All endpoints require authentication via Bearer token or API key with vault:read/vault:write scopes.

---

Cluster Management

GET /vault

List all Vault clusters in your organization.

Headers:

Authorization: Bearer <token>

Query Parameters:

Parameter	Type	Description
status	string	Filter by status: provisioning, running, sealed, error
limit	integer	Number of results (default: 20, max: 100)
offset	integer	Pagination offset

Response (200 OK):

[
  {
    "id": "uuid",
    "name": "prod-vault",
    "status": "running",
    "sealed": false,
    "storage_used_mb": 256,
    "total_secrets": 45,
    "api_address": "https://vault-xxx.sparbz.cloud",
    "auth_methods": ["token", "jwt", "approle"],
    "created_at": "2024-10-15T10:30:00Z"
  }
]

---

POST /vault

Create a new Vault cluster.

Request Body:

{
  "name": "string",
  "auto_unseal": true
}

Response (201 Created):

{
  "id": "uuid",
  "name": "prod-vault",
  "status": "provisioning",
  "sealed": true,
  "created_at": "2024-11-29T10:30:00Z",
  "unseal_keys": ["key1", "key2", "key3"]
}

---

GET /vault/:id

Get details of a specific Vault cluster.

Response (200 OK):

{
  "id": "uuid",
  "name": "prod-vault",
  "status": "running",
  "sealed": false,
  "storage_used_mb": 256,
  "total_secrets": 45,
  "api_address": "https://vault-xxx.sparbz.cloud",
  "auth_methods": ["token", "jwt", "approle"],
  "policies": ["admin", "developer", "readonly"],
  "secret_engines": ["kv", "database", "pki"],
  "high_availability": true,
  "replication_mode": "dr",
  "version": "1.15.0",
  "created_at": "2024-10-15T10:30:00Z"
}

---

Secret Management

GET /vault/:id/secret

List all secrets in the KV secret engine.

Query Parameters:

Parameter	Type	Description
path	string	Secret path prefix
list	boolean	List mode (recursive)

Response (200 OK):

{
  "request_id": "uuid",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "keys": ["app-config", "api-keys", "database-credentials"]
  },
  "warnings": null,
  "auth": null
}

---

POST /vault/:id/secret/:path

Create or update a secret.

Request Body:

{
  "data": {
    "username": "admin",
    "password": "secure-password",
    "api_key": "key-xxx"
  }
}

Response (200 OK):

{
  "request_id": "uuid",
  "lease_id": "secret/data/app-config/uuid",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created_time": "2024-11-29T10:30:00Z",
    "custom_metadata": null,
    "deletion_time": "",
    "destroyed": false,
    "version": 1
  }
}

---

GET /vault/:id/secret/:path

Retrieve a specific secret.

Response (200 OK):

{
  "request_id": "uuid",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "data": {
      "username": "admin",
      "password": "secure-password",
      "api_key": "key-xxx"
    },
    "metadata": {
      "created_time": "2024-11-29T10:30:00Z",
      "custom_metadata": null,
      "deletion_time": "",
      "destroyed": false,
      "version": 1
    }
  }
}

---

DELETE /vault/:id/secret/:path

Delete a secret.

Response (204 No Content)

---

Policy Management

GET /vault/:id/policies

List all policies in the Vault cluster.

Response (200 OK):

{
  "policies": [
    {
      "name": "admin",
      "description": "Full access to all secrets",
      "rules": "path \"secret/*\" { capabilities = [\"create\", \"read\", \"update\", \"delete\", \"list\"] }"
    },
    {
      "name": "developer",
      "description": "Read-only access to app secrets",
      "rules": "path \"secret/app/*\" { capabilities = [\"read\", \"list\"] }"
    }
  ]
}

---

POST /vault/:id/policies

Create or update a policy.

Request Body:

{
  "name": "api-consumers",
  "rules": "path \"secret/api/*\" { capabilities = [\"read\", \"list\"] } path \"secret/api/*/api-key\" { capabilities = [\"deny\"] }"
}

Response (200 OK)

---

GET /vault/:id/policies/:name

Get details of a specific policy.

Response (200 OK):

{
  "name": "developer",
  "rules": "path \"secret/app/*\" { capabilities = [\"read\", \"list\"] }",
  "created_at": "2024-10-15T10:30:00Z"
}

---

DELETE /vault/:id/policies/:name

Delete a policy.

Response (204 No Content)

---

Authentication Methods

GET /vault/:id/auth

List all enabled authentication methods.

Response (200 OK):

{
  "auth_methods": [
    {
      "type": "token",
      "description": "token based credentials",
      "path": "token/",
      "config": {
        "default_lease_ttl": 2764800,
        "max_lease_ttl": 2764800,
        "force_no_cache": false,
        "token_type": "default-service"
      }
    },
    {
      "type": "jwt",
      "path": "jwt/",
      "description": "JWT authentication"
    }
  ]
}

---

POST /vault/:id/auth/:method

Enable an authentication method.

Request Body:

{
  "type": "jwt",
  "description": "OIDC authentication",
  "config": {
    "oidc_discovery_url": "https://auth.example.com",
    "oidc_client_id": "vault-client",
    "bound_audiences": ["https://vault.example.com"]
  }
}

Response (204 No Content)

---

Encryption as a Service

POST /vault/:id/encrypt/:key

Encrypt plaintext data.

Request Body:

{
  "plaintext": "base64-encoded-data"
}

Response (200 OK):

{
  "cipher_text": "vault:v1:encrypted-data-here"
}

---

POST /vault/:id/decrypt/:key

Decrypt cipher text.

Request Body:

{
  "cipher_text": "vault:v1:encrypted-data-here"
}

Response (200 OK):

{
  "plaintext": "base64-encoded-data"
}

---

Token Management

GET /vault/:id/tokens

List active tokens.

Response (200 OK):

[
  {
    "accessor": "accessor-id",
    "type": "service",
    "display_name": "app-token",
    "ttl": 2592000,
    "issue_time": "2024-11-29T10:30:00Z",
    "expire_time": "2024-12-29T10:30:00Z",
    "last_renewal_time": "2024-11-29T15:45:00Z",
    "policies": ["admin", "developer"]
  }
]

---

POST /vault/:id/tokens

Create a new token.

Request Body:

{
  "display_name": "app-token",
  "ttl": 2592000,
  "policies": ["developer"]
}

Response (201 Created):

{
  "client_token": "s.token-xxx",
  "accessor": "accessor-id",
  "display_name": "app-token",
  "ttl": 2592000,
  "issue_time": "2024-11-29T10:30:00Z",
  "expire_time": "2024-12-29T10:30:00Z",
  "policies": ["developer"]
}

---

DELETE /vault/:id/tokens/:accessor

Revoke a token by accessor.

Response (204 No Content)

---

Audit Logs

GET /vault/:id/audit

Get audit logs for the Vault cluster.

Query Parameters:

Parameter	Type	Description
limit	integer	Number of logs (default: 100, max: 1000)
offset	integer	Pagination offset
from	timestamp	Start time filter
to	timestamp	End time filter

Response (200 OK):

[
  {
    "timestamp": "2024-11-29T15:45:00Z",
    "request": {
      "operation": "UPDATE",
      "path": "secret/data/app-config",
      "client_token": "s.token-xxx",
      "client_address": "192.168.1.100",
      "user_agent": "Vault/1.15.0"
    },
    "response": {
      "status": 200,
      "duration_ms": 42
    },
    "auth": {
      "client_token": "s.token-xxx",
      "accessor": "accessor-id",
      "policies": ["admin"]
    },
    "error": null
  }
]

---

Error Responses

Code	Description
400	Bad Request - Invalid secret path or policy rules
401	Unauthorized - Invalid or missing token
403	Forbidden - Insufficient permissions (policy violation)
404	Not Found - Secret, policy, or cluster doesn't exist
409	Conflict - Secret or policy already exists
500	Internal Server Error
503	Service Unavailable - Vault cluster sealed

---

Common Use Cases

Storing Database Credentials

POST /vault/{vault_id}/secret/database/prod-db
{
  "data": {
    "username": "postgres",
    "password": "secure-password",
    "host": "db.example.com",
    "port": 5432,
    "database": "production"
  }
}

Setting Up Role-Based Access

POST /vault/{vault_id}/policies
{
  "name": "database-reader",
  "rules": "path \"secret/database/*\" { capabilities = [\"read\"] }"
}

Rotating Secrets

POST /vault/{vault_id}/secret/api-keys/current
{
  "data": {
    "api_key": "new-key-xxx",
    "rotated_at": "2024-11-29T10:30:00Z"
  }
}

Encrypting Sensitive Data

POST /vault/{vault_id}/encrypt/pii-key
{
  "plaintext": "base64-encoded-pii"
}