API Reference

Introduction

Version: v1

The BurnLinks API lets developers create and manage one-time secrets programmatically. Use this API when you need automation around secure secret sharing between systems, CI pipelines, internal tools, or support workflows.

Base URL

https://burnlinks.com/api/v1

Auth

Bearer PAT

Content Type

application/json

Environment URLs

Use environment-specific hosts to separate development/testing from production traffic.

Test Mode

https://burnlinks.com/api/v1

Use for local/dev integrations and pre-release validation.

Live Mode

https://burnlinks.com/api/v1

Use for production automations and real operational workflows.

API key management and authentication

Create a token with POST /auth/token. Use this when a new service/tool needs API access. Tokens are bound to your currently selected team.
Choose abilities: secrets:read for read-only use cases, and secrets:write when creating/updating/deleting secrets.
Store token securely. Never expose PATs in client-side code or public repositories.
Authenticate requests with this header:
```
Authorization: Bearer YOUR_TOKEN
```

Token creation example

curl -X POST "https://burnlinks.com/api/v1/auth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@example.com",
    "password": "password",
    "device_name": "ci-runner",
    "abilities": ["secrets:read", "secrets:write"]
  }'

Response format

Success example

{ 
  "message": "Secret created successfully.",
  "data": {
    "id": 12,
    "token": "...",
    "expire_mode": "views",
    "expire_value": 1
  }
}

Validation error example

{ 
  "message": "The given data was invalid.",
  "errors": {
    "expire_mode": [
      "The selected expire mode is invalid."
    ]
  }
}

Secrets endpoint reference

All endpoints are team-scoped. Tokens can only access secrets inside the token's team.

GET /secrets

When to use: list all secrets for dashboards and sync jobs.

Ability: secrets:read • Optional query: per_page (default: 15)

POST /secrets

When to use: create a new secret before sending to a recipient.

Ability: secrets:write • Required: content, expire_mode (views|minutes), expire_value (1-10080)

GET /secrets/{secret}

When to use: fetch one secret after selecting it from a list.

Ability: secrets:read

PUT /secrets/{secret}

When to use: update content or expiration strategy of an existing secret.

Ability: secrets:write • Optional fields: content, expire_mode, expire_value

DELETE /secrets/{secret}

When to use: remove secrets that are no longer needed or should be immediately invalidated.

Ability: secrets:write

Rate limits

Apply client-side retry logic with exponential backoff for 429 responses.

Authenticated requests

Burst: 40 req/sec
Sustained: 240 req/min

Useful headers

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Error handling

401 Missing or invalid token

403 Ability denied or token-team mismatch

404 Resource not found

422 Validation error

Recommended integration pattern

Retry only transient failures (429/5xx).
Do not retry 401/403 without operator action.
Log `message` and field-level `errors` from 422 responses.