Skip to Content
API ReferenceDelegation

Delegation API

delegate

Issues a delegation credential from an owner to an agent, granting specific scoped permissions.

function delegate(options: DelegateOptions): Promise<DelegationCredential>

Parameters

DelegateOptions

ParameterTypeRequiredDefaultDescription
agentstringYes---DID of the agent receiving the delegation
ownerstringYes---DID of the owner granting it
ownerKeyPairKeyPairYes---Owner’s signing key pair
scopesstring[]Yes---Permissions to grant (min 1)
constraintsDelegationConstraintsNo---Additional limits
validFromstringNo---ISO 8601 start time
validUntilstringNo---ISO 8601 expiration time
statusList{ url: string; index: number }No---Status list entry for revocation
parentDelegation{ token: string; parentOwnerPublicKey: Uint8Array }No---Parent delegation for chaining (see Delegation Chains)
maxChainDepthnumberNo3Maximum allowed chain depth

DelegationConstraints

FieldTypeDescription
maxTransactionValuenumberMaximum value per operation
validUntilstringISO 8601 expiration
allowedDomainsstring[]Permitted domains
rateLimitnumberMax operations per time window
[key: string]unknownAny custom constraint

Returns

DelegationCredential

FieldTypeDescription
tokenstringThe signed SD-JWT VC token (send this to services)
claimsDelegationClaimsThe decoded claims for local use

DelegationClaims

FieldTypeDescription
agentstringAgent DID
ownerstringOwner DID
scopesstring[]Granted scopes
constraintsDelegationConstraints | undefinedConstraints, if set
validFromstring | undefinedStart time
validUntilstring | undefinedExpiration time

Example

import { delegate, generateKeyPair } from "@credat/sdk";
 
const ownerKeyPair = generateKeyPair("ES256");
 
const delegation = await delegate({
  agent: "did:web:acme.com:agents:bot",
  owner: "did:web:acme.com",
  ownerKeyPair: ownerKeyPair,
  scopes: ["files:read", "files:write"],
  constraints: {
    allowedDomains: ["storage.acme.com"],
  },
  validUntil: "2026-06-01T00:00:00Z",
});

Errors

CodeWhen
DELEGATION_SCOPE_INVALIDEmpty scopes array, or scopes not a subset of parent delegation
DELEGATION_INVALIDParent delegation is invalid, or chain depth exceeds maxChainDepth

verifyDelegation

Verifies a delegation credential’s signature and expiration.

function verifyDelegation(
  token: string,
  options: VerifyDelegationOptions,
): Promise<DelegationResult>

Parameters

ParameterTypeRequiredDescription
tokenstringYesThe raw SD-JWT VC token from delegation.token

VerifyDelegationOptions

ParameterTypeRequiredDefaultDescription
ownerPublicKeyUint8ArrayYes---The owner’s public key
checkRevocation(entry: StatusListEntry) => Promise<boolean>No---Callback to check if a credential is revoked
maxChainDepthnumberNo3Maximum allowed chain depth for chained delegations
resolveSignerKey(agentDid: string) => Promise<Uint8Array>No---Resolve an agent’s public key by DID (required for chained delegations)

Returns

DelegationResult

FieldTypeDescription
validbooleanWhether the delegation is valid
agentstring | undefinedAgent DID (may be undefined if verification failed before parsing)
ownerstringOwner DID
scopesstring[]Granted scopes
constraintsDelegationConstraints | undefinedConstraints
validFromstring | undefinedStart time
validUntilstring | undefinedExpiration time
errorsVerificationError[]Errors (empty if valid)

Example

import { verifyDelegation } from "@credat/sdk";
 
const result = await verifyDelegation(delegation.token, {
  ownerPublicKey: ownerKeyPair.publicKey,
});
 
if (result.valid) {
  console.log(result.scopes);
} else {
  console.error(result.errors);
}

Errors in result

CodeMeaning
DELEGATION_SIGNATURE_INVALIDToken was not signed by the given public key
DELEGATION_EXPIREDDelegation has expired
DELEGATION_NOT_YET_VALIDDelegation’s validFrom is in the future
DELEGATION_REVOKEDDelegation was revoked via status list
DELEGATION_INVALIDChain depth exceeded, parent invalid, or missing resolveSignerKey
Last updated on
AgentCredentials