---
title: "Authentication"
description: "KingMinos accepts Bearer tokens only. Bare keys are rejected."
canonical: "https://kingminos.com/docs/api/authentication/"
sourceKind: "source-mdx"
---

import TryItLink from '../../../../components/docs/TryItLink.astro';

Every account route at `https://api.kingminos.com` requires:

```http
Authorization: Bearer <your-key>
```

Bearer only. A bare key is `401` `malformed`. KingMinos never echoes the key back.

Sign in at [app.kingminos.com](https://app.kingminos.com/login/) to mint a `km_` user token. Tenant API keys use the `osr_` prefix. Leftover access questions go to [support@outboundsync.com](mailto:support@outboundsync.com).

## Free credits

Every verified work-email account gets **10 free credits a day** (unused credits expire at midnight UTC). Personal and disposable email addresses do not qualify. Only the first workspace on your company’s email domain gets the daily grant; teammates join that workspace by invite. Anyone can still sign up and buy credits.

Welcome and onboarding grants do not expire — they last until you spend them. KingMinos spends the credits that expire soonest first, so today’s free credits are used before one-time grants and purchased credits. Purchased pay-as-you-go credits sit in your balance under the [KingMinos Service Terms](https://kingminos.com/terms/). Full pricing and FAQ: [kingminos.com/pricing/](https://kingminos.com/pricing/).

## Quick test

<TryItLink method="GET" path="/v1/capabilities" />

`GET /health` needs no key. The first authenticated call can be the catalog:

```bash
curl 'https://api.kingminos.com/v1/capabilities' \
  -H 'Authorization: Bearer <your-key>'
```

A `200` proves the key is valid and shows the live capabilities.

## 401 shape

Unauthorized responses use the shared error envelope. `detail` is one of:

| `detail` | Meaning |
| --- | --- |
| `missing` | No `Authorization` header. |
| `malformed` | The header is not `Bearer <token>`. |
| `mismatch` | The key did not match. |

`hint` is a static one-liner. `request_id` is the Cloudflare `cf-ray` when present.

## SFDC Named Credentials

Salesforce Named Credential / Custom auth does not send Auth Parameters off the Salesforce side. The External Credential must list `Authorization` under Custom Headers, and that header must be `Bearer <key>`. Empty Custom Headers show up as `401` `missing`.

Do not import the full `openapi.yaml` into Salesforce External Services — it collapses to Type Any. The full document stays at `/openapi.yaml` for humans and agents.

## Scopes

Normal capability keys can call the POST routes and read runs. `DELETE /v1/subjects/{subject_key}` requires the `erase` scope. A house env key with `*` also matches. Flow capability keys cannot erase.

`GET /v1/balance`, `/v1/balance/ledger`, `/v1/balance/history`, `/v1/balance/forecast`, `/v1/balance/health`, and `GET /v1/usage` require the `billing:read` scope on a `km_` key. `billing:read` is not implied by `capability:*`. New `km_` tokens include it. A signed-in session can call these routes without that scope. Tenant `osr_` keys are `401`. See [Balance and usage](/docs/api/balance/).

## Idempotency

Capability POSTs accept `Idempotency-Key`. A `429` or `503` does not spend the key — retry the same one. A completed run replayed with the same key returns the original decision (`replayed: true`).