# API keys

If you (or your developers) want to integrate with us programmatically — uploading placements, pulling status, receiving webhooks — you authenticate with an API key.

## When to use API keys

Most creditor partners don't need API keys. The dashboard, CSV upload, and (eventually) accounting integrations cover most workflows.

You probably want an API key if you're:

* Building a custom integration between us and your internal systems.
* Uploading placements at a volume where the dashboard or CSV is impractical.
* Querying status programmatically into a data warehouse.

## When the key is issued

You get exactly one API key when your account finishes onboarding. The dashboard's onboarding wizard mints it once **all** of the following are true:

* Your account status is `verified` (KYB review complete).
* Stripe Connect payouts are enabled on your account.
* A Master Services Agreement is on file.

Until those gates pass, the API key endpoint refuses to mint a key and the wizard shows you what's still pending. There is no self-serve "create new key" button beyond the one-time issuance.

## Key format

Keys look like `ca_xxxxxxxx_yyyyyyyy...`. The `xxxxxxxx` prefix identifies which key it is (we look it up by prefix), and the `yyyyyyyy...` half is the secret. We store only a bcrypt hash of the secret half, so we can't ever show you the key again.

Treat the full key like a password. Don't commit it to version control, don't share it, don't paste it into chat.

## Where to find your key on the dashboard

Once issued, the key is shown on **Settings → API Key** in the dashboard. You can copy it from there.

> **Heads up:** the current dashboard shows the full key on this page. If you've lost your key or you think it's compromised, contact us to rotate it — there is no self-serve rotate or revoke button in the UI yet.

## Using an API key

Send it as a Bearer token in the `Authorization` header:

```
Authorization: Bearer ca_xxxxxxxx_yyyyyyyy...
```

## Rotating or revoking a key

There is no self-serve rotate/revoke flow in the dashboard today. To rotate a compromised key, [contact support](/troubleshooting/contact-support.md) — we'll mint a new one and invalidate the old one for you. The rotation is logged as a `creditor.api_key_issued` audit event.

## Scopes

Today every API key has the same scope: full read/write access to your tenant's data. Granular read-only vs. read-write scopes are planned but not yet available.

## Webhooks

A single outbound webhook URL can be configured under **Settings → Webhook URL**. We POST status-change events to that URL signed with HMAC-SHA256.

The dashboard does **not** currently have per-event endpoint subscription, signing-secret rotation, or a built-in test-event flow. You set one URL, you get all events. Per-event subscriptions are planned but not yet available.

## Rate limits

API calls are rate-limited per key and per tenant. Exceeding the limit returns HTTP 429 with a `Retry-After` header. Use standard exponential backoff.

The exact limit depends on your tier — contact your account manager if you need higher throughput.

## Versioning

The API is versioned with a `/v1/` prefix. We don't have a formal deprecation calendar yet — when we ship a `/v2/`, we'll notify creditor partners well in advance.

## TODO

* Self-serve rotate / revoke UI (not yet shipped).
* Per-event webhook subscription + signing-secret rotation (planned).
* Granular API key scopes (planned).

***

Last reviewed: 2026-05-24 by Customer Success.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.moderncollections.io/account-and-settings/api-keys.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.