Generate and scope an API key
API keys authenticate your server-side requests to the Meridian platform. This guide walks through creating a least-privilege key, restricting it to specific endpoints and IP ranges, and rotating it without downtime.
Written by Dana Whitfield
Updated Jun 14, 2026
Before you begin
You'll need workspace admin rights and the Meridian CLI installed. Confirm your version with meridian --version — this guide assumes v4.2.0 or later.
Note: Keys created in the sandbox environment are prefixed mk_test_ and never touch live data. Swap to a production key only after you've verified the flow end-to-end.
Create a scoped key
Run the create command with an explicit scope. Meridian keys are deny-by-default, so a key with no scopes can read nothing — you grant exactly the permissions each service needs.
# create a read-only key scoped to two endpoints
meridian keys create \
--name "reporting-service" \
--scope invoices:read,usage:read \
--allow-ip 203.0.113.0/24
→ key created: mk_live_a91f… (store it now — shown once)
Available scopes
Each scope maps to a read or write permission on a resource group. Combine only what a service needs — over-broad keys are the most common finding in security reviews.
| Scope | Method | Grants |
|---|---|---|
| invoices:read | GET | List and retrieve invoices |
| webhooks:write | POST | Register and update webhook endpoints |
| keys:delete | DELETE | Revoke keys — grant sparingly |
Rotate without downtime
Meridian supports overlapping keys: create the replacement, deploy it, then revoke the old one once traffic has fully shifted. There is never a window where both are invalid.
- Create the new key with the same scope set as the outgoing one.
- Roll it out to every service reading from your secrets manager.
- Confirm zero requests on the old key in the audit log, then revoke it.
Feedback