Shipeasy
APIOperations

Update an API key's label

Renames a key or re-notes what it is for. Only name and description are editable — everything that gives the key its authority (type, env, scopes,…

Renames a key or re-notes what it is for. Only name and description are editable — everything that gives the key its authority (type, env, scopes, expires_at) is fixed at mint, because the worker derives the read env and permissions from the key itself. To change any of those, rotate: mint a replacement and revoke this one.

Omitted fields are left untouched; send null to clear one. Returns the updated key row. Revoked keys can still be relabelled (the audit trail outlives the credential). Returns 404 if no such key exists in the project.

Use case

A key minted by shipeasy setup carries an auto-composed provenance label — rename it to the service that actually holds it and note the rotation owner.

PATCH
/api/admin/keys/{id}

Authorization

bearerSdkKey
AuthorizationBearer <token>

Pass an admin SDK key as Authorization: Bearer sdk_admin_…. Mint via POST /api/admin/keys with type: "admin".

In: header

Path Parameters

id*string

Stable opaque key id (UUID) returned by create / list.

Length1 <= length <= 128

Header Parameters

X-Project-Id?string

Project the request operates on. Optional — defaults to the project the SDK key belongs to; pass it only to scope a multi-project key (the generated client sets it once from its configuration, so per-call callers never thread it).

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://shipeasy.ai/api/admin/keys/string" \  -H "Content-Type: application/json" \  -d '{    "name": "checkout-service · production",    "description": "Held by the checkout service; rotation owner is the payments team"  }'
{
  "id": "3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90",
  "type": "server",
  "env": "prod",
  "created_at": "2026-05-09T16:01:22.000Z",
  "revoked_at": null,
  "expires_at": null,
  "created_by_email": "ana@example.com",
  "name": "checkout-service · production",
  "description": "Held by the checkout service; rotation owner is the payments team",
  "scopes": [
    "gates:evaluate",
    "events:write"
  ],
  "last4": "a1b2"
}
{
  "error": "Malformed request (bad JSON, missing project scope).",
  "code": "BAD_REQUEST"
}
{
  "error": "Missing or invalid admin SDK key.",
  "code": "UNAUTHORIZED"
}

{
  "error": "Key is valid but not allowed to act on this project.",
  "code": "FORBIDDEN"
}

{
  "error": "The resource does not exist or is not visible to the caller.",
  "code": "NOT_FOUND"
}

{
  "error": "A resource with this name already exists in the project.",
  "code": "ALREADY_EXISTS"
}

{
  "error": "The request body failed structural (schema) validation.",
  "code": "VALIDATION"
}

Was this page helpful?