Manage permissions from your backend

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.

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.

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.

Enforce policies on app-owned wallets

Understand allowed, denied, and approval-required signing outcomes.

Integrate user consent

Let people consent and complete the required Portal interactions.

Policy JSON reference

Define selectors, conditions, approval requirements, and adjustable settings.

Permissions REST reference

Find the server-side methods, routes, and request contracts.

Get Started

Set Up Project

Create and Manage Wallets

Sign and Transact