> ## 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.

# Permissions REST SDK

> Server-secret permissions methods and their REST routes

These methods are available on `ParaRestClient` from `@getpara/rest-sdk`. The `apiKey` constructor option must contain your **server secret key** for these operations. Keep this client on your backend. A public application key or a user-session core SDK client does not grant this authority.

```typescript theme={null}
import { ParaRestClient } from "@getpara/rest-sdk";

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

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

None of these methods opens Portal. Backend access can inspect user settings and consent, but cannot consent, approve as a user, or edit a user’s personal parameter values.

## Arguments and errors

The signatures below are positional. `reference` identifies an authorization scope, policy version, and requirement. `context` and `query` fields become query parameters; `body` is JSON. [Permissions types](/v3/references/types/permissions) defines these inputs and the principal response fields.

Every method accepts optional `ParaRestCallOptions` (`signal?: AbortSignal`, `idempotencyKey?: string`). The REST SDK reports non-success responses as `ParaRestError`; preserve its status and response when handling authorization, validation, or revision-conflict failures. Writes using `expectedRevision` reject stale revisions rather than overwriting a newer change.

## Policy discovery

### listPartnerPolicies

Lists active policies within their effective time window for the authenticated partner, including targeted definitions. Drafts and inactive versions are excluded.

```typescript theme={null}
listPartnerPolicies(options?: ParaRestCallOptions): Promise<PermissionsV2PolicyListResponse>
```

```text Route theme={null}
GET /v1/permissions-v2/policies
```

### getPartnerPolicy

Reads an active policy within its effective time window for the authenticated partner.

```typescript theme={null}
getPartnerPolicy(policyId: string, options?: ParaRestCallOptions): Promise<PermissionsV2PolicyResponse>
```

```text Route theme={null}
GET /v1/permissions-v2/policies/{policyId}
```

### listPartnerPolicyVersions

Lists versions that are active or were previously active for the authenticated partner. Drafts and versions that were never activated are excluded.

```typescript theme={null}
listPartnerPolicyVersions(policyId: string, options?: ParaRestCallOptions): Promise<PermissionsV2PolicyVersionsResponse>
```

```text Route theme={null}
GET /v1/permissions-v2/policies/{policyId}/versions
```

## User consent

### listUserPolicyConsents

Lists consent requests and current consent state for the selected user wallet.

```typescript theme={null}
listUserPolicyConsents(userId: string, context: PermissionsV2ConsentListContext, options?: ParaRestCallOptions): Promise<PermissionsV2DelegationConsentDiscoveryResponse>
```

```text Route theme={null}
GET /v1/permissions-v2/users/{userId}/delegation-consents
```

### getUserPolicyConsent

Reads the selected policy’s current consent state for a user wallet.

```typescript theme={null}
getUserPolicyConsent(userId: string, policyId: string, context: PermissionsV2WalletContext, options?: ParaRestCallOptions): Promise<PermissionsV2DelegationConsentView>
```

```text Route theme={null}
GET /v1/permissions-v2/users/{userId}/delegation-consents/{policyId}
```

## User parameters

### listUserAdjustablePolicies

Lists policies with adjustable parameters available to the user.

```typescript theme={null}
listUserAdjustablePolicies(userId: string, options?: ParaRestCallOptions): Promise<PermissionsV2UserAdjustablePolicyListResponse>
```

```text Route theme={null}
GET /v1/permissions-v2/users/{userId}/user-parameters
```

### getUserPolicyParameters

Reads parameter declarations, saved values, and the current settings revision.

```typescript theme={null}
getUserPolicyParameters(userId: string, policyId: string, options?: ParaRestCallOptions): Promise<PermissionsV2UserParameterView>
```

```text Route theme={null}
GET /v1/permissions-v2/users/{userId}/user-parameters/{policyId}
```

### listUserPolicyParameterHistory

Lists saved parameter revisions for the user and policy.

```typescript theme={null}
listUserPolicyParameterHistory(userId: string, policyId: string, query?: PermissionsV2HistoryOptions, options?: ParaRestCallOptions): Promise<PermissionsV2UserParameterHistory>
```

```text Route theme={null}
GET /v1/permissions-v2/users/{userId}/user-parameters/{policyId}/history
```

## Approval configuration

### listConfigurableApprovalRequirements

Lists approval requirements that expose configuration in an authorization scope.

```typescript theme={null}
listConfigurableApprovalRequirements(authorizationScopeId: string, options?: ParaRestCallOptions): Promise<PermissionsV2ConditionalRequirementList>
```

```text Route theme={null}
GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/requirements
```

### getConfigurableApprovalRequirement

Reads a configurable approval requirement in a specific policy version and authorization scope.

```typescript theme={null}
getConfigurableApprovalRequirement(reference: PermissionsV2ApprovalRequirementReference, options?: ParaRestCallOptions): Promise<PermissionsV2ConditionalRequirementView>
```

```text Route theme={null}
GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/policies/{policyId}/versions/{policyVersion}/requirements/{requirementId}
```

### getApprovalConfiguration

Reads the stored configuration and revision for an approval requirement. Returns `404` before the first write; use `getEffectiveApprovalConfiguration` to read defaults with `configuration: null`.

```typescript theme={null}
getApprovalConfiguration(reference: PermissionsV2ApprovalRequirementReference, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationConfigurationView>
```

```text Route theme={null}
GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/policies/{policyId}/versions/{policyVersion}/requirements/{requirementId}/configuration
```

### getEffectiveApprovalConfiguration

Reads the approval requirement after applying its current configuration.

```typescript theme={null}
getEffectiveApprovalConfiguration(reference: PermissionsV2ApprovalRequirementReference, options?: ParaRestCallOptions): Promise<PermissionsV2EffectiveAuthorizationConfiguration>
```

```text Route theme={null}
GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/policies/{policyId}/versions/{policyVersion}/requirements/{requirementId}/configuration/effective
```

### updateApprovalConfiguration

Updates the configurable values explicitly permitted by an approval requirement.

```typescript theme={null}
updateApprovalConfiguration(reference: PermissionsV2ApprovalRequirementReference, body: PermissionsV2AuthorizationConfigurationWrite, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationConfigurationView>
```

```text Route theme={null}
PUT /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/policies/{policyId}/versions/{policyVersion}/requirements/{requirementId}/configuration
```

### resetApprovalConfiguration

Clears configured overrides and restores the requirement’s defaults.

```typescript theme={null}
resetApprovalConfiguration(reference: PermissionsV2ApprovalRequirementReference, expectedRevision: number, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationConfigurationView>
```

```text Route theme={null}
PUT /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/policies/{policyId}/versions/{policyVersion}/requirements/{requirementId}/configuration
```

Sends `{ expectedRevision, values: {} }` to the same update route.

### listApprovalConfigurationHistory

Lists configuration revisions for an approval requirement.

```typescript theme={null}
listApprovalConfigurationHistory(reference: PermissionsV2ApprovalRequirementReference, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationConfigurationHistory>
```

```text Route theme={null}
GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/policies/{policyId}/versions/{policyVersion}/requirements/{requirementId}/configuration/history
```

## Roles and wallet scopes

### getUserApprovalAssignments

Reads roles and attributes assigned to a user in an authorization scope.

```typescript theme={null}
getUserApprovalAssignments(authorizationScopeId: string, userId: string, options?: ParaRestCallOptions): Promise<PermissionsV2AuthoritySetView>
```

```text Route theme={null}
GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/users/{userId}/assignments
```

### listAuthorizationScopeMembers

Lists users and their assignments in an authorization scope.

```typescript theme={null}
listAuthorizationScopeMembers(authorizationScopeId: string, query?: PermissionsV2AuthorizationScopeMemberListOptions, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationScopeMembers>
```

```text Route theme={null}
GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/members
```

### replaceUserApprovalAssignments

Replaces a user’s complete role and attribute assignments in an authorization scope.

```typescript theme={null}
replaceUserApprovalAssignments(authorizationScopeId: string, userId: string, body: PermissionsV2AuthoritySetWrite, options?: ParaRestCallOptions): Promise<PermissionsV2AuthoritySetView>
```

```text Route theme={null}
PUT /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/users/{userId}/assignments
```

Replaces the full assignment set. An empty `assignments` array removes all assignments in this scope.

### listUserApprovalAssignmentHistory

Lists revisions of a user’s authority assignments in an authorization scope.

```typescript theme={null}
listUserApprovalAssignmentHistory(authorizationScopeId: string, userId: string, options?: ParaRestCallOptions): Promise<PermissionsV2AuthoritySetHistory>
```

```text Route theme={null}
GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/users/{userId}/assignments/history
```

### getWalletAuthorizationScope

Reads the authorization scope currently bound to a wallet.

```typescript theme={null}
getWalletAuthorizationScope(walletId: string, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationScopeBindingView>
```

```text Route theme={null}
GET /v1/permissions-v2/wallets/{walletId}/authorization-scope
```

### setWalletAuthorizationScope

Sets the authorization scope bound to a wallet using its current revision.

```typescript theme={null}
setWalletAuthorizationScope(walletId: string, body: PermissionsV2AuthorizationScopeBindingWrite, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationScopeBindingView>
```

```text Route theme={null}
PUT /v1/permissions-v2/wallets/{walletId}/authorization-scope
```

### listWalletAuthorizationScopeHistory

Lists revisions of a wallet’s authorization-scope binding.

```typescript theme={null}
listWalletAuthorizationScopeHistory(walletId: string, query?: PermissionsV2HistoryOptions, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationScopeBindingHistory>
```

```text Route theme={null}
GET /v1/permissions-v2/wallets/{walletId}/authorization-scope/history
```

## Approval cases

### listPartnerApprovalCases

Lists approval cases for the authenticated partner without granting a user decision.

```typescript theme={null}
listPartnerApprovalCases(query?: PermissionsV2CaseListOptions, options?: ParaRestCallOptions): Promise<PermissionsV2ConditionalApprovalPartnerCaseList>
```

```text Route theme={null}
GET /v1/permissions-v2/approval-cases
```

### getPartnerApprovalCase

Reads a partner approval case without impersonating an approver.

```typescript theme={null}
getPartnerApprovalCase(caseId: string, options?: ParaRestCallOptions): Promise<Omit<PermissionsV2ConditionalApprovalCaseView, 'decision'>>
```

```text Route theme={null}
GET /v1/permissions-v2/approval-cases/{caseId}
```

## Usage

### getPartnerPolicyUsage

Reads a current spending-usage snapshot for an app-owned or user-owned wallet.

```typescript theme={null}
getPartnerPolicyUsage(policyId: string, context: PermissionsV2PartnerUsageContext, options?: ParaRestCallOptions): Promise<PermissionsV2PolicyUsage>
```

```text Route theme={null}
GET /v1/permissions-v2/wallets/{walletId}/policies/{policyId}/usage
```

When `context.userId` is supplied, uses `GET /v1/permissions-v2/users/{userId}/policies/{policyId}/usage` with `walletId` in the query. This returns current meter usage, not a transaction preview.