API Access

Envault provides a REST API for programmatic access to secrets. This is useful for CI/CD pipelines, custom integrations, or building your own clients.

Authentication

All API requests must include the Authorization header with a valid Service Token.

Do not use your personal User JWT for automated scripts. Generate a Service Token from the project settings.

Authorization: Bearer evt_live_...

Base URL

https://your-envault-instance.com/api/v1

Error Handling

The API uses standard HTTP status codes.

Code	Meaning	Description
`200`	OK	Request succeeded.
`401`	Unauthorized	Invalid or missing API token.
`403`	Forbidden	Token lacks permission for this resource.
`404`	Not Found	Project or secret not found.
`429`	Too Many Requests	You have exceeded the rate limit.
`500`	Server Error	Something went wrong on our end.

Rate Limits

To ensure system stability, Envault enforces strict rate limits on API access using a sliding window algorithm:

Personal/Human Tokens: 60 requests per minute per user/IP.
Service Tokens: 600 requests per minute per project context.

If you exceed these limits, you will receive a 429 Too Many Requests response.

Endpoints

Ownership Transfer (Project Settings/API)

These endpoints support the ownership transfer handshake:

POST /api/projects/:id/transfer/initiate
POST /api/projects/:id/transfer/accept
POST /api/projects/:id/transfer/reject

Notes:

initiate is owner-only.
accept / reject are target-user-only.
Overlapping pending requests per project are blocked.
Requests expire after 48 hours.

Get Project Secrets

Retrieve all decrypted secrets for a specific project environment.

GET /projects/:projectId/secrets

Parameters

Name	Type	Description
`environment`	`string`	The environment to fetch (e.g., `production`, `preview`). Default: `development`.

Response

{
  "secrets": {
    "DATABASE_URL": "postgres://user:pass@db:5432/db",
    "API_KEY": "sk_test_12345",
    "NEXT_PUBLIC_API_URL": "https://api.example.com"
  }
}

Example Request

curl -X GET "https://envault.app/api/v1/projects/proj_123/secrets?environment=production" \
  -H "Authorization: Bearer evt_live_abc123"

const response = await fetch('https://envault.app/api/v1/projects/proj_123/secrets?environment=production', {
  headers: {
    Authorization: 'Bearer evt_live_abc123'
  }
});

const data = await response.json();
console.log(data.secrets);

API Overview