Permissions types

Shared inputs, revision rules, and lifecycle results for permissions methods

The signatures use the SDK’s input and response type names. Not every response type is a named export from the client package. To type a result without importing an internal package, derive it from the method:

import type ParaCore from "@getpara/core-sdk";
import type { ParaRestClient } from "@getpara/rest-sdk";

type SignatureCollection = Awaited<
  ReturnType<ParaCore["createApprovalSignatureCollection"]>
>;
type BackendAssignments = Awaited<
  ReturnType<ParaRestClient["getUserApprovalAssignments"]>
>;

The types below describe the data each method accepts or returns. The caller must still satisfy the method’s access requirements.

Resource context

interface PermissionsV2WalletContext {
  walletId: string;
}

interface PermissionsV2ConsentListContext extends PermissionsV2WalletContext {
  pendingTransactionId?: string;
}

interface PermissionsV2ApprovalRequirementReference {
  authorizationScopeId: string;
  policyId: string;
  policyVersion: string;
  requirementId: string;
}

interface PermissionsV2UsageContext extends PermissionsV2WalletContext {
  chainId?: string;
  tokenAddress?: string;
}

interface PermissionsV2PartnerUsageContext extends PermissionsV2UsageContext {
  userId?: string;
}

Usage reads require chainId even though the type marks it optional. Use the wallet type’s network form: a bare decimal chain ID such as "8453" for EVM, or a prefixed network identifier such as solana:mainnet, sui:mainnet, cosmos:cosmoshub-4, stellar:testnet, or the Stellar network passphrase. Usage reads do not accept eip155: IDs or unprefixed Cosmos chain IDs. tokenAddress is an EVM token address, or the exact asset identity used in the policy for other wallet types.

policyVersion identifies an immutable authored version. expectedRevision below identifies a mutable settings revision. Read the resource before writing and submit its current revision; use zero when no revision exists. A stale revision does not silently overwrite a newer update.

Adjustable parameters

type PermissionsV2UserParameterSave = {
  policyVersion: string;
  policyHash: string;
  expectedRevision: number;
  values: Record<string, string>;
};

type PermissionsV2UserParameterReset = {
  policyVersion: string;
  policyHash: string;
  expectedRevision: number;
};

values maps declared parameter IDs to their values. Amounts use the policy fact’s units, including base units where specified; do not substitute a formatted currency amount.

PermissionsV2UserAdjustablePolicyListResponse contains policies, an array of parameter views.

PermissionsV2UserParameterView identifies the user, application, policy version, and hash, and includes parameters, revision, and provenance (default or personal). Each parameter descriptor has id, label, defaultValue, fact, and optional asset and window.

• status: "ready" includes current values; stored revisions also include configurationHash.
• status: "needs_confirmation" includes previousValues. They are not confirmed values for the current policy version.

Saving parameter values is separate from granting standing consent. Use the current consent state to determine whether Portal confirmation is needed.

Approval configuration and authority

type PermissionsV2AuthorizationConfigurationWrite = {
  expectedRevision: number;
  values: Record<string, string | number>;
};

type PermissionsV2AuthoritySetWrite = {
  expectedRevision: number;
  assignments: Array<
    | { kind: "role"; name: string }
    | { kind: "attribute"; name: string; value: string }
  >;
};

type PermissionsV2AuthorizationScopeBindingWrite = {
  expectedRevision: number;
  authorizationScopeId: string;
};

Workflow configuration changes only the settings declared by the policy, within their value types and bounds. An authenticated user must meet the policy’s manager eligibility; a trusted backend uses its server secret to administer configuration within the same declared limits. Personal spending parameters are separate settings chosen by the wallet owner.

Assignment writes replace the complete set for that user and scope. They determine who qualifies under the policy’s role and attribute rules, so your backend must authorize callers before changing assignments.

PermissionsV2AuthorizationConfigurationView, PermissionsV2AuthoritySetView, and PermissionsV2AuthorizationScopeBindingView return their resource identity, revision, changedAt, and changedBy. Configuration views also contain values and configurationHash. PermissionsV2EffectiveAuthorizationConfiguration returns the authored requirement, stored configuration (or null), and effectiveRequirement.

Result	Principal fields
PermissionsV2ConditionalRequirementView	policyId, policyVersion, policyHash, ruleId, requirementId, and the authored requirement.
PermissionsV2ConditionalRequirementList	requirements: an array of requirement views.
PermissionsV2AuthorizationScopeCapabilities	Partner, application, scope, and user IDs plus requirements. Each entry identifies a policy/version/hash, rule and requirement, with canManageConfiguration: true.

Capabilities describe which requirements the current user can manage. They are not a list of other scope members or a signing authorization.

Signature collection

type PermissionsV2TransactionSignatureCollection = {
  requestId: string;
  walletId: string;
  transaction:
    | { format: "safe_eip712"; typedDataJson: string; chainId: string }
    | { format: "evm_typed_data"; typedDataJson: string; chainId: string }
    | { format: "evm_transaction"; transactionBase64: string; chainId: string }
    | { format: "solana_transaction"; transactionBase64: string }
    | { format: "cosmos_transaction"; signMode: "DIRECT" | "AMINO"; signDocBase64: string }
    | { format: "stellar_xdr"; transactionXdr: string; networkPassphrase: string }
    | { format: "sui_transaction"; transactionBase64: string };
};

type PermissionsV2ConditionalApprovalSignature = {
  walletId: string;
  signature: string;
};

interface SignApprovalTransactionParams {
  caseId: string;
  walletId: string;
}

The collection request identifies the transaction wallet. A signature submission identifies the signer’s wallet; they need not be the same wallet. The backend derives the canonical signing payload from the transaction rather than accepting caller-provided policy facts.

PermissionsV2ApprovalSignatureCollectionResult returns caseId, status, and expiresAt. PermissionsV2ApprovalSigningPayload returns caseId, transaction, payloadDigest, and signingPayloadBase64. PermissionsV2ApprovalSignatures adds signatures, each containing walletId, signature, and actorId.

Collected signatures are not an onchain submission. Your chain-specific integration remains responsible for assembling and broadcasting the intended transaction.

Discovery, consent, and cases

Result	Principal fields
PermissionsV2PolicyListResponse	policies: policy views.
PermissionsV2PolicyResponse	policy: one policy view.
PermissionsV2PolicyVersionsResponse	versions: policy views.
Policy view	policyId, policyVersion, policyHash, lifecycle, activation, optional consent binding, and authored policy.
PermissionsV2DelegationConsentDiscoveryResponse	requests, each containing policy and consent.
PermissionsV2DelegationConsentView	Resource IDs, policy version/hash, status, optional configuration hash and grant/expiry/revocation timestamps.
PermissionsV2ConditionalApprovalCaseView	kind (conditional_approval), caseId, status, optional evidence, request, requirementIdentity, currentStageIndex, stages, decisions, expiresAt, optional terminalReason, and caller-specific decision capability.

Policy lifecycle values are active, inactive, superseded, and archived. Activation timestamps additionally govern when a policy is effective. Consent status is pending, standing, manual_review, revoked, or expired.

Approval case status is pending, completed, rejected, expired, or invalidated. completed means the approval requirement was satisfied; it does not itself establish that a transaction was broadcast.

Replacing or deactivating the policy that required an approval invalidates the approval if it has not completed. An invalidated approval cannot complete; submit the request again under the current policy.

For an invalidated case, terminalReason can say why. For example, "requirement_unavailable" means the approval requirement is no longer available, such as after the policy that required it was replaced or deactivated.

An approval case’s decision says whether the current user can decide and, if not, why: not_eligible, initiator, already_decided, case_terminal, or authority_changed. Partner backend case reads omit this user-specific field. Reading an initiated case does not grant approval authority.

Usage and history

PermissionsV2PolicyUsage identifies the policy, wallet, user (or null), application, and snapshot timestamp asOf. It includes the applicable parameter configuration and meters.

Each meter identifies the rule and condition, fact, operator, ruleEffect, assetType (NATIVE, ERC20, or TOKEN), optional tokenAddress, chain, window, bucket start/reset time, and string-valued limitBaseUnits, committedBaseUnits, reservedBaseUnits, and usedBaseUnits. remainingBaseUnits may be null. A usage snapshot is not a transaction evaluation result.

interface PermissionsV2HistoryOptions {
  beforeRevision?: number;
}

interface PermissionsV2CaseListOptions {
  limit?: number;
  beforeCaseId?: string;
}

interface PermissionsV2AuthorizationScopeMemberListOptions {
  limit?: number;
  afterUserId?: string;
}

Pass the response cursor into the corresponding next request.

Result	Principal fields
PermissionsV2UserParameterHistory	revisions: policy version/hash, revision, provenance, values, and change time; optional nextBeforeRevision.
PermissionsV2AuthorizationScopeBindingHistory	revisions: wallet-scope binding views; optional nextBeforeRevision.
PermissionsV2ConditionalApprovalCaseList	cases: approval case views; optional nextBeforeCaseId.
PermissionsV2ConditionalApprovalPartnerCaseList	cases: case views without caller-specific decision; optional nextBeforeCaseId.
PermissionsV2AuthorizationScopeMembers	members: authority-set views; optional nextAfterUserId.
PermissionsV2AuthoritySetHistory	assignments: authority-set revision views.
PermissionsV2AuthorizationConfigurationHistory	configurations: configuration revision views.

listAccessibleApprovalCases returns { cases: PermissionsV2ConditionalApprovalCaseView[] } without a pagination cursor. Portal URL methods return a string to open through your application’s browser integration.