Manage permissions from your backend

Assign approval authority, configure declared workflow settings, and read policy state with your server secret

Your backend administers approval authority and reads permission state for its partner scope. These methods manage assignments, scopes, and settings permitted by an authored policy. They do not rewrite policy definitions or add approval stages; changing the rules requires the authoring and publication lifecycle.

A server secret does not grant user consent, edit a user’s personal policy parameters, or submit a person’s approval decision.

What you’ll learn: connect the REST SDK, assign roles and attributes, bind wallets to an authorization scope, configure allowed workflow settings, and inspect current state and history.

Connect your backend

Use ParaRestClient from @getpara/rest-sdk. Its permissions methods send your server secret in X-API-Key; the public application key and a user’s SDK session are different authentication boundaries.

import { ParaRestClient } from '@getpara/rest-sdk';

const para = new ParaRestClient({
  apiKey: process.env.PARA_SERVER_SECRET!,
  env: 'BETA',
});

const { policies } = await para.listPartnerPolicies();

Keep the secret on your backend. Authorize your application’s callers before forwarding administrative requests to Para. Follow REST setup for environments and authentication.

Conditional approvals and user-adjustable limits are enabled per app. Until Para enables them, writes to approval assignments, wallet authorization scopes, and approval configuration return 403 PERMISSIONS_V2_EXTENSION_UNAVAILABLE, as do listUserAdjustablePolicies and getUserPolicyParameters. Contact Para to enable either feature.

Assign roles and attributes

An authorization scope separates a set of assignments and approval configuration within your application. For example, each business using your product can have its own scope. The policy defines which roles or attributes qualify someone to approve or manage configuration; assignments connect authenticated Para users to those declarations.

For a user with no existing assignment record, create the initial set with expectedRevision: 0:

const authorizationScopeId = 'treasury';
const userId = process.env.PARA_USER_ID!;

const assigned = await para.replaceUserApprovalAssignments(
  authorizationScopeId,
  userId,
  {
    expectedRevision: 0,
    assignments: [
      { kind: 'role', name: 'approver' },
      { kind: 'attribute', name: 'department', value: 'finance' },
    ],
  },
);

Use names that match your policy. replaceUserApprovalAssignments replaces the whole set, rather than appending entries. To remove all assignments, submit assignments: [] with the current revision. To change a subset, read getUserApprovalAssignments and include the assignments you intend to retain.

Only the partner backend can list other members with listAuthorizationScopeMembers. A signed-in client cannot use its own session to enumerate the scope or grant itself roles.

Bind a wallet to the scope

The wallet binding determines which scope supplies the assignments and configuration for approval evaluation. Set an initial binding with revision zero; use the existing binding’s revision when changing it.

const walletId = process.env.PARA_WALLET_ID!;

await para.setWalletAuthorizationScope(walletId, {
  expectedRevision: 0,
  authorizationScopeId,
});

const binding = await para.getWalletAuthorizationScope(walletId);

Wallet access remains subject to the partner boundary. Binding a wallet does not transfer ownership or grant the backend access to a user’s signing session.

Configure declared approval settings

A policy can expose named configuration values for an approval requirement. The backend may change those values only within the policy’s declared constraints; it cannot replace the requirement with arbitrary JSON through these methods.

Discover requirements, then read the effective configuration for one:

const { requirements } = await para.listConfigurableApprovalRequirements(
  authorizationScopeId,
);

const requirement = requirements[0];
if (requirement) {
  const reference = {
    authorizationScopeId,
    policyId: requirement.policyId,
    policyVersion: requirement.policyVersion,
    requirementId: requirement.requirementId,
  };

  const effective = await para.getEffectiveApprovalConfiguration(reference);
  // effective.effectiveRequirement includes the applied configuration.
  // effective.configuration is null when no configuration record exists.
}

Use updateApprovalConfiguration(reference, { expectedRevision, values }) with the declared configuration names. Use revision zero for the first write, or the revision from the current configuration for an update. resetApprovalConfiguration(reference, expectedRevision) restores the policy defaults by writing an empty values map.

Revision checks prevent one administrator from silently overwriting another’s changes. On a conflict, read the current record and reconcile the intended update before submitting again.

A policy may also authorize authenticated configuration managers. Assigning a manager role is a backend operation; that user’s ability to change configuration is still limited by the policy. Neither path lets the backend change personal user-adjustable parameters.

Read state without acting for the user

Task	REST SDK methods
Inspect authored definitions and versions	listPartnerPolicies, getPartnerPolicy, listPartnerPolicyVersions
Inspect user consent for a wallet	listUserPolicyConsents, getUserPolicyConsent
Read personal parameter settings	listUserAdjustablePolicies, getUserPolicyParameters
Inspect workflow settings	getConfigurableApprovalRequirement, getApprovalConfiguration, getEffectiveApprovalConfiguration
Read approval authority	getUserApprovalAssignments, listAuthorizationScopeMembers
Monitor approval cases	listPartnerApprovalCases, getPartnerApprovalCase
Read current spend usage	getPartnerPolicyUsage

For example, read consent and saved parameters for a known user and policy:

const policyId = process.env.PARA_POLICY_ID!;

const consent = await para.getUserPolicyConsent(userId, policyId, { walletId });
const parameters = await para.getUserPolicyParameters(userId, policyId);

These reads are scoped to your partner and the requested subject. They do not grant consent or permission to write the user’s values. Approval cases expose workflow state; the backend does not receive a method to submit a human decision.

Usage is a current snapshot, not a transaction preview or a reservation for a future transaction. The snapshot distinguishes committed and reserved spending and reports the applicable window and limit. Signing still evaluates the actual request.

getPartnerPolicyUsage requires chainId in the wallet type’s network form, such as 8453, solana:mainnet, sui:mainnet, cosmos:cosmoshub-4, or stellar:mainnet. To read a token limit, pass tokenAddress as an EVM contract address or as the exact asset identity used in the policy.

Inspect resource histories

Use listUserPolicyParameterHistory, listUserApprovalAssignmentHistory, listWalletAuthorizationScopeHistory, and listApprovalConfigurationHistory for the corresponding revision records. Policy versions are available separately through listPartnerPolicyVersions.

Follow returned pagination cursors where provided. Policy version history includes versions that are or were active; use the authoring tools to inspect drafts.