Authentication

The Meridian HR API authenticates requests with API keys. Each key:

• belongs to exactly one org,
• is itself an OrgMember — it carries a role, and that role's permissions are the only thing it can do, and
• must be presented on every request along with the X-Org-Id header for the org it belongs to.

Keys can be rotated and revoked at any time. The plaintext secret is shown once at creation.

Creating an API key

You can create keys either from the dashboard (Settings → API keys) or via the API itself, signed in as a user with api_key.manage:

POST /core/api-keys
Authorization: Bearer <user-access-token>
X-Org-Id: <org-id>
Content-Type: application/json

{
  "name": "payroll-export-bot",
  "role_id": "<role-id>",
  "expires_at": "2027-01-01T00:00:00Z"
}

The response includes the secret exactly once:

{
  "id": "ak_01HXYZ...",
  "name": "payroll-export-bot",
  "role_id": "...",
  "secret": "mer_live_sk_a1b2c3...",
  "prefix": "mer_live_sk_a1b2c3",
  "expires_at": "2027-01-01T00:00:00Z",
  "created_at": "2026-05-27T10:00:00Z"
}

Store the secret immediately — it cannot be retrieved later. Only the prefix is shown in subsequent list calls.

Calling the API

Send the secret as a bearer token and pin the org with X-Org-Id:

curl https://api.meridianhr.co/corehr/employees \
  -H "Authorization: Bearer mer_live_sk_a1b2c3..." \
  -H "X-Org-Id: 01HX...."

The key's role decides what comes back — request a resource the role doesn't have permission for and you'll get 403 forbidden. Cross-org requests (key from org A trying to read org B) are blocked at the database layer by Row-Level Security.

Lifecycle

Rotation issues a new secret and invalidates the old one immediately. Revocation is irreversible.

Best practices

• One key per integration. It makes rotation and audit-trail attribution clean.
• Scope with roles. Give the integration its own role with only the permissions it needs — don't reuse an Admin role.
• Set an expires_at. Long-lived secrets are a liability. Rotate at least quarterly.
• Watch the audit log. Every key action — create, rotate, revoke, and every API call the key makes — is recorded under the key's OrgMember identity.