Skip to content

API — Getting Started

Authentication, Base URLs, Versioning, and Rate Limits

Document Version: 1.1.0
Last Updated: 2026-04-04

1. Base URL

All API endpoints are relative to your MazeVault installation:

https://<your-mazevault-host>/api/v1/

Example: 

https://vault.example.com/api/v1/health

2. API Versioning

Version Status Path Prefix
v1 Current — Stable /api/v1/
v2 Reserved (Zero-Knowledge endpoints) /api/v2/

Note

Use API v1 for all standard integrations. API v2 is reserved for zero-knowledge encryption operations and is not required for typical use cases.

3. Authentication

Option A: Bearer Token (Interactive / Session-based)

Obtain a token via one of the authentication endpoints, then include it in all subsequent requests:

GET /api/v1/secrets HTTP/1.1
Host: vault.example.com
Authorization: Bearer ***REMOVED***

Obtain Token — Local Auth (SRP)

Step 1: Initialize 

POST /api/v1/auth/srp/init HTTP/1.1
Content-Type: application/json

{
  "username": "john.doe"
}

Response: 

{
  "salt": "base64-encoded-salt",
  "server_public_key": "base64-encoded-B"
}

Step 2: Verify 

POST /api/v1/auth/srp/verify HTTP/1.1
Content-Type: application/json

{
  "username": "john.doe",
  "client_public_key": "base64-encoded-A",
  "client_proof": "base64-encoded-M1"
}

Response: 

{
  "access_token": "***REMOVED***",
  "token_type": "Bearer",
  "expires_in": 86400,
  "server_proof": "base64-encoded-M2"
}

Obtain Token — OAuth 2.0 Client Credentials

POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<id>&client_secret=<secret>

Note

The OAuth 2.0 token endpoint is at /oauth/token (not under /api/v1/).

Response: 

{
  "access_token": "***REMOVED***",
  "token_type": "Bearer",
  "expires_in": 86400
}

Obtain Token — Universal Auth (API Key)

POST /api/v1/auth/universal-auth/login HTTP/1.1
Content-Type: application/json

{
  "client_id": "<your-client-id>",
  "client_secret": "<your-client-secret>"
}

Response: 

{
  "access_token": "***REMOVED***",
  "token_type": "Bearer",
  "expires_in": 86400
}

Option B: API Token (Programmatic)

Create an API token in the MazeVault web interface (User Settings → API Tokens), then use it directly:

GET /api/v1/secrets HTTP/1.1
Host: vault.example.com
Authorization: Bearer mvt_abc123def456...

4. Rate Limits

Endpoint Category Limit Window Header
Authentication 10 1 minute X-RateLimit-Limit
API (authenticated) 100 1 minute X-RateLimit-Limit
OCSP 1000 1 minute —
Health Unlimited — —

Rate limit headers returned with every response:

Header Description
X-RateLimit-Limit Maximum requests per window
X-RateLimit-Remaining Remaining requests in current window
X-RateLimit-Reset Unix timestamp when the window resets

When rate limited, the API returns 429 Too Many Requests.

5. Error Responses

All errors follow a consistent JSON format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Secret name is required",
    "details": [
      {
        "field": "name",
        "message": "This field is required"
      }
    ],
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Code Meaning Typical Cause
200 OK Successful GET, PUT
201 Created Successful POST (resource created)
204 No Content Successful DELETE
400 Bad Request Validation error, malformed request
401 Unauthorized Missing or expired token
403 Forbidden Insufficient permissions
404 Not Found Resource does not exist
409 Conflict Duplicate resource, version conflict
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Unexpected server error

Common Error Codes

Error Code Description
AUTH_REQUIRED No authentication token provided
AUTH_EXPIRED Token has expired — re-authenticate
AUTH_INVALID Token is invalid or malformed
PERMISSION_DENIED User lacks required permission
VALIDATION_ERROR Request body validation failed
RESOURCE_NOT_FOUND Requested resource does not exist
RESOURCE_CONFLICT Resource already exists or version conflict
RATE_LIMITED Rate limit exceeded
CSRF_INVALID CSRF token missing or invalid
LICENSE_EXPIRED License has expired — contact support

6. Pagination

List endpoints support pagination:

GET /api/v1/secrets?page=1&per_page=25 HTTP/1.1

Response headers:

Header Description
X-Total-Count Total number of resources
X-Page Current page number
X-Per-Page Items per page

7. Health Check

Verify API availability:

GET /api/v1/health HTTP/1.1

Response: 

{
  "status": "healthy",
  "version": "1.8.0",
  "components": {
    "database": "healthy",
    "redis": "healthy",
    "ocsp": "healthy"
  }
}