Authentication

API key types, where to get them, and how to keep them safe

Authentication

Every MarginFront API call needs an API key. This doc tells you where to get one, how to use it, which type to use when, and how to keep it safe.

---

How to use an API key

Every request to the MarginFront API includes an x-api-key header with your key:

x-api-key: mf_sk_test_...

That’s it. No OAuth dance, no token refresh, no session cookies. One header, one key, every request.

With curl:

curl https://api.marginfront.com/v1/verify \
  -H "x-api-key: $MF_API_SECRET_KEY"

With the Node SDK:

import { MarginFrontClient } from "@marginfront/sdk";

const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

The SDK handles the header for you — you just pass the key to the constructor and it takes care of the rest.

---

Two types of API key

MarginFront issues two kinds of keys, and they have different permissions. This is the same pattern Stripe uses — if you’ve used Stripe’s API before, this will feel familiar.

Key type	Prefix	Where it’s safe to put	What it can do
Secret	mf_sk_...	Backend only. Never ship to the browser.	Everything: read, create, update, delete.
Publishable	mf_pk_...	Safe in browser code. Public-facing.	Read-only on public endpoints (/v1/verify, public pricing info). All writes (POST/PUT/PATCH/DELETE) are rejected with 403.

When to use which

• Server-side backend code (Node, Python, Go, Ruby, whatever) — use a secret key. Your backend is trusted, so it can do anything.
• Browser code / mobile app / anywhere the key could leak — use a publishable key. If a visitor reads the key out of your page source, the worst they can do is read public info. They cannot create, update, or delete anything.
• A hosted billing portal for your customers — neither. Use portal sessions instead, which issue short-lived, customer-scoped tokens.

What happens if you use the wrong one

• Publishable key trying to POST/PATCH/DELETE → 403 Forbidden with a message telling you to use a secret key
• Secret key used in browser code → technically works, but you’ve leaked your main credential to anyone viewing the page. Don’t do this.

---

Where to get an API key

1. Log into the MarginFront dashboard
2. Go to Developer Zone → API Keys
3. Either use an existing key or click “Create new key”
4. Pick the type: secret or publishable
5. Copy it immediately — you can’t see the full value again after the first time. If you lose it, you’ll have to create a new one.

Keys look like mf_sk_test_... or mf_sk_live_... (secret) and mf_pk_test_... or mf_pk_live_... (publishable), depending on environment.

---

Checking that your key works

The simplest test is the /v1/verify endpoint. It takes no parameters, just your key. If everything’s set up right, you’ll get a 200 response with your org info.

curl https://api.marginfront.com/v1/verify \
  -H "x-api-key: $MF_API_SECRET_KEY"

Success response:

{
  "organization": {
    "id": "41a1bb3d-557a-42ce-acfe-ce79bbd47cea",
    "name": "Your Org Name"
  },
  "verified": true,
  "createdAt": "2026-04-11T16:45:27.012Z",
  "updatedAt": "2026-04-11T16:47:29.475Z"
}

If you get 401: Your key is either missing, malformed, or wrong. Double-check the header name (x-api-key, not Authorization: Bearer). If it’s definitely formatted right, the key itself is probably wrong — go back to the dashboard and copy a fresh one.

If you get 403: You’re probably using a publishable key on an endpoint that requires writes. Use a secret key. See the table above.

If you get nothing (connection refused / timeout): The API server isn’t running. If you’re hitting localhost, start it with cd apps/api-nest && npm run dev.

---

The API key alone identifies your organization

You don’t need to pass your organization ID anywhere. The API key alone tells MarginFront which org you are — the backend looks up your key, finds the org it belongs to, and uses that for the request. Every endpoint under /v1/<resource> works this way.

This is the Stripe / Anthropic / OpenAI pattern. One credential, one identity, no redundant IDs to pass around.

(If you need to find your org ID for support or debugging purposes, hit /v1/verify with your key and look at the organization.id field in the response.)

---

Every API call is logged

MarginFront automatically logs every API-key-authenticated request. The audit log captures:

• The key ID (a non-secret reference to which of your keys was used)
• Your organization ID
• The endpoint (HTTP method + URL path)
• The response status code
• The IP address of the caller
• The timestamp

The full secret value of the key is never logged — only its non-secret ID. The audit log is stored in your own database and is only visible to you.

What this means for compliance

If you need to answer “who did what when” for a compliance audit or incident investigation, this is where you look. The data accumulates from the moment your key makes its first call and is retained indefinitely.

Checking your own audit log

(The Usage History UI on Developer Zone → API Keys is the intended way to view this. If it’s not there yet, you can query the api_key_usage_logs table directly via Prisma Studio in development.)

---

Keeping your API key safe

The short version

• Never commit keys to git. Not in code, not in config files, not in comments. Use environment variables.
• Never ship secret keys to browser code. Secret keys belong on your backend. If you need to show billing data to a customer in their browser, use a publishable key for reads, or portal sessions for customer-specific views.
• Never share keys across environments. Use separate keys for development, staging, and production.
• Rotate keys if you suspect a leak. Create a new key in the dashboard, update your code to use it, then revoke the old one.

The longer version

Environment variables are the right pattern. Load the key from an environment variable at runtime:

# In your shell / deployment config:
export MF_API_SECRET_KEY="mf_sk_test_..."

// In your code:
const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

This way the key never hard-codes into files that could end up in git or a Docker image layer.

For local development: put the key in .env.local (or whatever your framework uses) and make sure that file is in .gitignore. Never put it in .env that gets committed.

For production: use your platform’s secret management (Vercel env vars, AWS Secrets Manager, Doppler, etc.). Don’t put production keys in plaintext config files.

If a key does leak:

1. Go to the dashboard immediately
2. Create a replacement key
3. Update your code/deployment to use the new key
4. Revoke the leaked key from the dashboard
5. Check the audit log (see above) for any unusual activity using the old key