Skip to main content

Documentation Index

Fetch the complete documentation index at: https://yanhgming.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

The settings endpoints let you manage programmatic access to the Marlin API and configure where Marlin sends event notifications. API keys authenticate every REST API request. Webhooks deliver signed event payloads to your server when things happen — invoices get paid, subscriptions are canceled, and so on. Marlin signs every webhook delivery with HMAC-SHA256 so you can verify the payload is genuine.

​
API keys

​
GET /api/settings/api-keys

List all active (non-revoked) API keys on your account. The response omits the actual secret value — only a prefix of the key hash is returned for identification purposes. You cannot recover a secret key after creation.

​
Response — 200 OK

Returns an array of API key objects.
​
id
string
Database UUID for the key.
​
label
string | null
Human-readable label you assigned at creation.
​
keyPrefix
string
First 8 characters of the key hash. Use this to identify a key without exposing the secret.
​
lastUsedAt
string | null
ISO 8601 timestamp of the most recent authenticated request, or null if the key has never been used.
​
createdAt
string
ISO 8601 creation timestamp.
curl https://api.marlin.dev/api/settings/api-keys \
  --header "Authorization: Bearer sk_live_abc123"

​
POST /api/settings/api-keys

Create a new API key. The full secret value (key) is returned once in this response and cannot be retrieved again. Store it immediately in a secrets manager or environment variable.
The secret key is only shown at creation time. If you lose it, you must create a new key and revoke the old one.

​
Request body

​
label
string
Optional human-readable label to identify this key (max 100 characters). Useful when you have multiple keys for different environments or services.

​
Response — 201 Created

​
key
string
The full secret API key, e.g. mlk_abc123.... This is the only time this value is returned. Copy it now.
curl --request POST https://api.marlin.dev/api/settings/api-keys \
  --header "Authorization: Bearer sk_live_abc123" \
  --header "Content-Type: application/json" \
  --data '{ "label": "Production server" }'

​
DELETE /api/settings/api-keys/:id

Revoke an API key. Once revoked, any request authenticated with that key returns 401 Unauthorized. This action is immediate and irreversible.

​
Path parameters

​
id
string
required
The API key’s database UUID (from the list response).

​
Response — 200 OK

​
success
boolean
Always true when the key is successfully revoked.
Error cases
  • NOT_FOUND (404) — The key does not exist, already belongs to another account, or has already been revoked.
curl --request DELETE \
  https://api.marlin.dev/api/settings/api-keys/key_01HXYZ \
  --header "Authorization: Bearer sk_live_abc123"

​
Webhook configuration

Marlin delivers signed POST requests to your webhook URL whenever a billing event occurs. The payload is signed with HMAC-SHA256 using your webhook secret and delivered in a marlin-signature header — verify this signature in your handler before processing the event. Available event types: invoice.created, invoice.paid, invoice.voided, invoice.overdue, subscription.created, subscription.activated, subscription.paused, subscription.resumed, subscription.canceled, subscription.past_due, customer.created, customer.updated, payment.received, payment.confirmed.

​
GET /api/settings/webhook

Retrieve the current webhook endpoint URL configured on your account.

​
Response — 200 OK

​
webhookUrl
string | null
The currently configured webhook URL, or null if no endpoint is set.
curl https://api.marlin.dev/api/settings/webhook \
  --header "Authorization: Bearer sk_live_abc123"

​
PUT /api/settings/webhook

Set or update your webhook endpoint URL. Pass null to remove the endpoint and stop all webhook deliveries.

​
Request body

​
webhookUrl
string | null
required
A valid HTTPS URL that Marlin will POST event payloads to, or null to disable webhooks.

​
Response — 200 OK

​
webhookUrl
string | null
The newly configured webhook URL, or null if webhooks were disabled.
Error cases
  • VALIDATION_ERROR (400) — webhookUrl is not a valid URL.
curl --request PUT https://api.marlin.dev/api/settings/webhook \
  --header "Authorization: Bearer sk_live_abc123" \
  --header "Content-Type: application/json" \
  --data '{ "webhookUrl": "https://example.com/webhooks/marlin" }'
Use the @marlin/sdk webhook verification helper to validate the marlin-signature header in your handler before trusting any event payload.