---
title: "Register an existing provider key for platform use"
method: POST
path: "/keys/register"
tags: ["KMS"]
---

# Register an existing provider key for platform use

`POST /keys/register`

Explicitly onboards a key that already exists inside a provider into the platform's persistent key reference store, so the platform can discover and use it later. The body identifies the key by its `providerId` and `alias`, with an optional `kid`. This does not create or import key material; the key must already live in the named provider. The response confirms registration and echoes the alias, providerId, and kid. Returns 400 if the provider or key cannot be found.

## Request body

- RegisterKeyReferenceRequest — Request body for registering an existing provider key for platform use.
  - `providerId` string, required — The provider that holds the key.
  - `alias` string, required — Alias to register the key under.
  - `kid` string — Optional kid for the key.

## Response `201`

Key reference registered successfully

- RegisterKeyReferenceResponse — Response body for a registered key reference.
  - `registered` boolean, required — Whether the key was successfully registered.
  - `alias` string, required — The alias the key was registered under.
  - `providerId` string, required — The provider that holds the key.
  - `kid` string — Optional kid for the key.

## Other responses

- `400` — Bad request due to invalid input parameters or request body.
- `500` — An unexpected error occurred on the server.

---

[API](https://skmtc.dev/sphereon-opensource/apis/kms-rest-server-api.md) · [All operations](https://skmtc.dev/sphereon-opensource/apis/kms-rest-server-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sphereon-opensource/kms-rest-server-api/revisions/e9136cbde1c1/schema)