Delegate Key

Edit online

Delegates a key to an end user. Only keys created with delayDelegation: true can be delegated using this endpoint. This requirement ensures that you intentionally designate a key for later delegation, helping prevent accidental delegation of sensitive or treasury‑level keys.

When a key is delegated to an end user, all wallets that use this key as their signing key are also automatically delegated to the same user. This keeps key and wallet ownership consistent across the system.This operation is irreversible. After delegation, ownership of the key is permanently transferred to the end user.In most cases, if you want to implement wallet delegation, create the wallet by directly delegating it to an end user from the start, making it non‑custodial immediately. The delayed delegation feature is intended for situations where the key or wallet must be created before the end user has access to the system.

HTTP request

POST /keys/{keyId}/delegate

Authorization requirements

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token used to authenticate the request. See Authentication flows for instructions on generating this token.
`X-DFNS-USERACTION`	string	Yes	User action signature used to authorize change-inducing requests. See User Action Signing flows for instructions on generating this signature.

Path parameter

Parameter	Type	Required	Description
keyId	string	Yes	ID of the key to delegate. Minimum length: 1.

Request body

Field	Type	Required	Description
delegateTo	string	Yes	ID of the end user to whom the key will be delegated. Minimum length: 1.

curl --request POST \
  --url https://api.digitalassets.ibm.com/keys/{keyId}/delegate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-DFNS-USERACTION: <api-key>' \
  --data '
{
  "delegateTo": "<string>"
}
'

Response

200: Success

Example response:

{
  "keyId": "<string>",
  "status": "Delegated"
}