Custody credentials API

A regulated issuer has to prove who can change the keys behind its custody provider, and prove that changing them never leaks the keys. The custody credentials API answers both. Organization owners read the current custody configuration, probe replacement credentials before committing them, and rotate to new credentials, all without any endpoint ever returning secret material. The provider an organization locks at onboarding stays fixed, so a rotation replaces credentials for that provider and never switches custodians.

Use this API to operate custody for one organization. For how an organization picks its provider and what the lock means, see Custody providers. For the wallet balance that funds signing, see Custody wallet gas balance.

Access and scope

The organization endpoints act on the caller's active organization. The role you need depends on the operation:

• Reading the masked configuration and probing candidate credentials are open to any member of the active organization. A probe run by an organization owner or platform administrator also records the validation outcome on the custody record; a probe run by another member validates the credentials without persisting that outcome.
• Rotating credentials requires the organization owner role. A platform administrator may also rotate. The platform rejects any other caller with an authorization error before the handler runs.

An API key inherits the role of the account that created it, so a key can rotate credentials only when its owner holds the owner or administrator role.

Every read returns a masked view. The platform tracks where the credentials come from, when the provider locked, and whether the last validation passed, but it never returns the credential secret. The most an org-managed record exposes is a fingerprint that lets you confirm which credential version is active without revealing the credential itself.

The two admin endpoints span tenants and are reserved for platform administrators. Treat their results as platform-wide custody data and protect them accordingly.

Read the custody configuration

Read the active organization's custody configuration as a masked view. Use it to confirm the locked provider, see whether credentials are platform-managed or organization-managed, and check the last validation result before you rotate.

GET /api/v2/custody

curl "https://your-platform.example.com/api/v2/custody" \
  -H "X-Api-Key: YOUR_DALP_API_KEY"

{
  "data": {
    "provider": "dfns",
    "credentialSource": "org",
    "custodyLockedAt": "2026-05-17T09:10:29.428Z",
    "lastValidationStatus": "valid",
    "lastValidatedAt": "2026-06-20T11:02:14.005Z",
    "metadata": {
      "workspaceId": "or-1a2b3c"
    },
    "credentialVersion": 3,
    "rotatedAt": "2026-06-20T11:02:14.005Z",
    "credentialFingerprint": "a1b2c3d4"
  }
}

The response reports:

• provider: the custody provider locked for the organization.
• credentialSource: org when the organization supplied its own credentials, or platform when the deployment manages them.
• custodyLockedAt: when the provider locked, or null before the first wallet is created.
• lastValidationStatus: valid or invalid from the most recent probe, destroyed for an offboarded record, or null when no validation has run.
• lastValidatedAt: when the last validation ran.

Organization-managed records add four fields that platform-managed records omit, because nothing derived from platform credentials is exposed:

• metadata: non-secret provider scope, such as the provider workspace identity or a vault scope.
• credentialVersion: the active credential version, which increments on each rotation.
• rotatedAt: when the credentials last rotated.
• credentialFingerprint: a short non-secret fingerprint of the active credentials.

When the organization has no custody record yet, the endpoint returns a not-found error rather than an empty object.

Probe candidate credentials

Validate replacement credentials against the provider before you store them. The probe runs the provider's own check and reports whether the credentials work. It never stores the credentials and never advances the active credential version, so it is safe to run before a rotation. When an organization owner or platform administrator runs the probe against their active organization, and the organization already has a custody record for the same provider, the probe records the validation outcome on that record. It still writes no credential secret. If the organization has no custody record yet, or the probed provider differs from the existing record, the probe returns the result without updating anything. Run it first so a rotation never flips the active credential version to a value the provider would reject.

POST /api/v2/custody/test-credentials

Send the provider and the credential payload. The payload carries authentication material only; platform-curated connection settings are not accepted here. You can pass the provider workspace identity or vault scope you expect the credentials to match, and the probe confirms them.

curl -X POST "https://your-platform.example.com/api/v2/custody/test-credentials" \
  -H "X-Api-Key: YOUR_DALP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "dfns",
    "credentials": { "auth": { "authToken": "...", "credId": "...", "privateKey": "..." } },
    "workspaceId": "or-1a2b3c"
  }'

{
  "data": {
    "ok": true,
    "checkedAt": "2026-06-24T22:00:00.000Z",
    "capability": "read",
    "workspaceVerified": true
  }
}

The response reports:

• ok: always true on success. A failed probe returns a credential error instead.
• checkedAt: when the probe ran.
• capability: the access the credentials proved, either read or create.
• workspaceVerified: true when the credentials matched the workspace or vault scope you passed.

The probe is callable during onboarding, before the organization exists, so a new tenant can confirm its credentials before it commits to a provider. With an active organization, the probe additionally checks the credentials against the custody record's pinned workspace.

Rotate credentials

Replace the active credentials for the organization's locked provider. The rotation validates the new credentials against the provider, then flips the active version only if they pass, so a bad payload never leaves the organization unable to sign.

PUT /api/v2/custody/credentials

Send the replacement credential payload. The provider is set by the lock and is not part of the request, so a rotation never switches custodians. Include metadata when you need to set or keep a provider workspace identity or vault scope, for example when adopting a platform-managed record and supplying its workspace pin for the first time.

curl -X PUT "https://your-platform.example.com/api/v2/custody/credentials" \
  -H "X-Api-Key: YOUR_DALP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credentials": { "auth": { "authToken": "...", "credId": "...", "privateKey": "..." } },
    "metadata": { "workspaceId": "or-1a2b3c" }
  }'

A successful rotation returns the same masked configuration shape as the read endpoint, with credentialVersion incremented and rotatedAt set to the rotation time. The response never contains the new credentials.

Rotation runs one at a time per organization and enforces a short cooldown between rotations. A rotation that arrives too soon after the previous one fails with a too-frequent error that tells you how long to wait before retrying.

Provider credential payloads

Each provider accepts a different authentication payload. Send only the authentication material; connection settings are platform-curated and rejected.

Authentication fields are secret material and belong inside the credentials object, under auth for every provider except local. Provider scope fields are non-secret identifiers, such as a provider workspace ID or a vault ID, sent at the top level of the request to pin which provider scope the credentials operate against.

Platform administrator endpoints

Platform administrators can read or destroy custody credentials for any organization by ID. These endpoints span tenants and require the global administrator role.

Destruction is final. It deletes the credential secrets and stamps the custody record with a terminal destroyed status. The record survives as a tombstone, so later reads still succeed but expose nothing credential-derived, and the organization cannot rotate or modify the destroyed record afterward. Use this only when offboarding an organization for good.

Errors

For the full registry and handling guidance, see Error handling.

Related

• Custody providers for provider selection, the lock, and signer routing.
• Custody wallet gas balance for the wallet balance that funds signing.
• Organizations administration API for the cross-tenant organization roster.
• Getting started with API integration
• Error handling