> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getpara.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/v3/general/permissions-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.

```ts theme={null}
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](/v3/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`:

```ts theme={null}
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.

```ts theme={null}
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:

```ts theme={null}
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.

<Note>
  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.
</Note>

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:

```ts theme={null}
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.

<CardGroup cols={2}>
  <Card title="Enforce policies on app-owned wallets" icon="shield-check" href="/v3/rest/permissions">
    Understand allowed, denied, and approval-required signing outcomes.
  </Card>

  <Card title="Integrate user consent" icon="user-check" href="/v3/react/guides/permissions">
    Let people consent and complete the required Portal interactions.
  </Card>

  <Card title="Policy JSON reference" icon="code" href="/v3/references/permissions/policy-json">
    Define selectors, conditions, approval requirements, and adjustable settings.
  </Card>

  <Card title="Permissions REST reference" icon="server" href="/v3/references/rest/permissions">
    Find the server-side methods, routes, and request contracts.
  </Card>
</CardGroup>