---
title: "Issue a cloud-bookkeeping service key"
method: POST
path: "/admin/service-keys"
tags: ["API Keys", "Admin"]
---

# Issue a cloud-bookkeeping service key

`POST /admin/service-keys`

## Request

- Base URL: `https://api.medianfi.com/api/v1`
- URL: `https://api.medianfi.com/api/v1/admin/service-keys`
- Auth: HTTP bearer

Requires a human bearer JWT whose user id is present in the immutable server-owned SUPER_ADMIN_USER_IDS allowlist. The server binds the key to the configured non-human service principal and fixed accountant:* scope. The plaintext key is returned once and is never stored.

## Request body

- CreateServiceApiKeyInput
  - `name` string, required
  - `expiresInDays` integer: Requested lifetime in days, at most 7 (#1147). The server also caps it at its configured service-key default.

## Response `201`

Service key created; copy the plaintext key now

- CreatedServiceApiKeyResponse
  - `success` true, required
  - `data` CreatedServiceApiKey, required
    - `id` string, uuid, required
    - `companyId` string, uuid, required: Configured service-key home company; not caller-selectable.
    - `name` string, required
    - `prefix` string, required: Non-secret lookup prefix; never the complete credential.
    - `scopes` string[], required: Newly issued service keys receive exactly accountant:*.
    - `createdByUserId` string, uuid, required: Configured non-human service-principal user id.
    - `issuedByUserId` string, uuid, nullable: Human allowlisted super-admin who issued the key.
    - `lastUsedAt` string, date-time, nullable, required
    - `expiresAt` string, date-time, nullable, required
    - `revokedAt` string, date-time, nullable, required
    - `revokedByUserId` string, uuid, nullable
    - `createdAt` string, date-time, required
    - `usageCountLast24h` integer
    - `usageCountLast7d` integer
    - `plainTextKey` string, required: Returned once. Store in a secrets manager before discarding the response. Format (#1147): `mdn_svc_v1_` + base64url of 32 random bytes + `_` + 8 lowercase hex CRC-32 of everything before the final underscore. Service keys minted before this format (`mdn_live_`) keep verifying until they expire or are revoked.

## Other responses

- `401`: Authentication required
- `403`: Insufficient permissions or not a company member
- `422`: Validation error
- `503`: The dedicated service principal is not configured

---

[API](https://skmtc.dev/medianfi/apis/median-api.md) · [All operations](https://skmtc.dev/medianfi/apis/median-api/llms.txt) · [OpenAPI document](https://skmtc.dev/medianfi/apis/median-api/revisions/20090ea32b0d?raw)