---
title: "Create an API key"
method: POST
path: "/v1/api-keys"
tags: ["API Keys"]
---

# Create an API key

`POST /v1/api-keys`

Create a named API key for an environment. The full token is returned once in this response — store it immediately. A requested `role` is clamped so it never exceeds the caller's own role.

## Request body

- object
  - `name` string — You optionally set a name for the key. Defaults to `default`.
  - `environment` string — You optionally set the environment: `sandbox` or `prod`. Defaults to `sandbox`.
  - `role` string — You optionally set the role: `owner`, `admin`, `issuer`, `verifier`, `issuer-verifier`, or `reader`. Clamped to at most the caller's role.

## Response `201`

The API key was created. The full token is returned once.

- object
  - `uuid` string, uuid — You receive the UUID for this API key.
  - `name` string — You receive the API key name.
  - `environment` string — You receive the environment for this key: `sandbox` or `prod`.
  - `role` string — You receive the role granted to this key.
  - `created_at` string, date-time — You receive the timestamp when the key was created.
  - `token` string — You receive the full API key token. Store it now — it is only returned once.
  - `note` string — You receive a reminder that the token is only shown once.

---

[API](https://skmtc.net/didit-protocol/apis/didit-credentials-api.md) · [All operations](https://skmtc.net/didit-protocol/apis/didit-credentials-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/didit-protocol/didit-credentials-api/versions/e4eddba66557/schema)