> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microcrop.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate server-to-server requests with your organization API key.

All partner API calls authenticate with your organization's **API key**, sent in the
`x-api-key` header. The key authenticates as your organization with **`ORG_ADMIN`**
rights on its own resources.

```bash theme={null}
curl https://app.microcrop.app/api/organizations/me \
  -H "x-api-key: $MICROCROP_API_KEY"
```

## Getting your API key

The plaintext key is shown **exactly twice**: when the organization is created, and each
time you rotate it. Treat the value as opaque — the prefix differs by how the
organization was created (`org_live_…` or `mc_…`) and is not part of the contract.

<Steps>
  <Step title="At signup">
    `POST /api/auth/register-organization` returns `201` with the key at
    `data.organization.apiKey`. Store it then.
  </Step>

  <Step title="From the dashboard">
    Log in to the [dashboard](https://app.microcrop.app) and read it there.
  </Step>

  <Step title="By rotating">
    `POST /api/organizations/me/api-key/rotate` returns `{ apiKey, apiSecret }` in
    plaintext once, and the previous key stops working immediately.
  </Step>
</Steps>

<Warning>
  **`GET /api/organizations/me` does not return your API key.** It strips `apiKey`,
  `apiSecret` and `webhookSecret` from the response — the endpoint is readable by every
  org role, and the key authenticates as an admin. If you have lost the key, rotate it.
</Warning>

## Managing the key

| Method | Path                                   | Returns                                                                             | Role        |
| ------ | -------------------------------------- | ----------------------------------------------------------------------------------- | ----------- |
| `GET`  | `/api/organizations/me/api-key`        | Masked metadata: `keyPrefix`, `last4`, `masked`, `active`, `rotatedAt`, `createdAt` | `ORG_ADMIN` |
| `POST` | `/api/organizations/me/api-key/rotate` | `{ apiKey, apiSecret }` — plaintext, once                                           | `ORG_ADMIN` |
| `POST` | `/api/organizations/me/api-key/revoke` | The masked metadata with `active: false`                                            | `ORG_ADMIN` |

A revoked key is rejected by `x-api-key` auth with `401 UNAUTHORIZED` even though the
organization still exists. Revocation is reversible by rotating.

```bash theme={null}
# check which key is live without ever printing it
curl https://app.microcrop.app/api/organizations/me/api-key -H "x-api-key: $KEY"
# → { "success": true, "data": { "keyPrefix": "org_live_", "last4": "9f21",
#     "masked": "org_live_********9f21", "active": true, "rotatedAt": null, "createdAt": "…" } }
```

<Warning>
  Your API key is a **secret**. Keep it server-side, never ship it in browser or mobile
  clients, and rotate it if exposed. It grants full admin access to your organization's
  data.
</Warning>

## Auth errors

| Status | Code                | Meaning                                                                                                |
| ------ | ------------------- | ------------------------------------------------------------------------------------------------------ |
| `401`  | `UNAUTHORIZED`      | Missing, invalid, or revoked `x-api-key`.                                                              |
| `403`  | `FORBIDDEN`         | Organization is deactivated, or the action requires KYB verification.                                  |
| `403`  | `TIER_NOT_ENTITLED` | A settlement action on a policy your tier does not cover — see [Service tiers](/guides/service-tiers). |

## Notes

* **Bearer JWT** tokens also exist, but they're for the MicroCrop dashboard
  (short-lived, per-user, with per-role capabilities). For server-to-server
  integration, always use the `x-api-key` header.
* Authentication identifies *which organization* you are; it does not bypass
  [KYB gating](/requirements#whats-gated) or the tier gate.
* Requests are rate limited — see [Rate limits](/guides/rate-limits).