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.

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.

1. At signup

   POST /api/auth/register-organization returns 201 with the key at data.organization.apiKey. Store it then.

2. From the dashboard

   Log in to the dashboard and read it there.

3. By rotating

   POST /api/organizations/me/api-key/rotate returns { apiKey, apiSecret } in plaintext once, and the previous key stops working immediately.

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.

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.

# 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": "…" } }

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.

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.

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 or the tier gate.
• Requests are rate limited — see Rate limits.