Permissions REST SDK

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.

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

listPartnerPolicies(options?: ParaRestCallOptions): Promise<PermissionsV2PolicyListResponse>

Route

GET /v1/permissions-v2/policies

getPartnerPolicy

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

getPartnerPolicy(policyId: string, options?: ParaRestCallOptions): Promise<PermissionsV2PolicyResponse>

Route

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.

listPartnerPolicyVersions(policyId: string, options?: ParaRestCallOptions): Promise<PermissionsV2PolicyVersionsResponse>

Route

GET /v1/permissions-v2/policies/{policyId}/versions

listUserPolicyConsents

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

listUserPolicyConsents(userId: string, context: PermissionsV2ConsentListContext, options?: ParaRestCallOptions): Promise<PermissionsV2DelegationConsentDiscoveryResponse>

Route

GET /v1/permissions-v2/users/{userId}/delegation-consents

getUserPolicyConsent

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

getUserPolicyConsent(userId: string, policyId: string, context: PermissionsV2WalletContext, options?: ParaRestCallOptions): Promise<PermissionsV2DelegationConsentView>

Route

GET /v1/permissions-v2/users/{userId}/delegation-consents/{policyId}

User parameters

listUserAdjustablePolicies

Lists policies with adjustable parameters available to the user.

listUserAdjustablePolicies(userId: string, options?: ParaRestCallOptions): Promise<PermissionsV2UserAdjustablePolicyListResponse>

Route

GET /v1/permissions-v2/users/{userId}/user-parameters

getUserPolicyParameters

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

getUserPolicyParameters(userId: string, policyId: string, options?: ParaRestCallOptions): Promise<PermissionsV2UserParameterView>

Route

GET /v1/permissions-v2/users/{userId}/user-parameters/{policyId}

listUserPolicyParameterHistory

Lists saved parameter revisions for the user and policy.

listUserPolicyParameterHistory(userId: string, policyId: string, query?: PermissionsV2HistoryOptions, options?: ParaRestCallOptions): Promise<PermissionsV2UserParameterHistory>

Route

GET /v1/permissions-v2/users/{userId}/user-parameters/{policyId}/history

Approval configuration

listConfigurableApprovalRequirements

Lists approval requirements that expose configuration in an authorization scope.

listConfigurableApprovalRequirements(authorizationScopeId: string, options?: ParaRestCallOptions): Promise<PermissionsV2ConditionalRequirementList>

Route

GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/requirements

getConfigurableApprovalRequirement

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

getConfigurableApprovalRequirement(reference: PermissionsV2ApprovalRequirementReference, options?: ParaRestCallOptions): Promise<PermissionsV2ConditionalRequirementView>

Route

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.

getApprovalConfiguration(reference: PermissionsV2ApprovalRequirementReference, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationConfigurationView>

Route

GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/policies/{policyId}/versions/{policyVersion}/requirements/{requirementId}/configuration

getEffectiveApprovalConfiguration

Reads the approval requirement after applying its current configuration.

getEffectiveApprovalConfiguration(reference: PermissionsV2ApprovalRequirementReference, options?: ParaRestCallOptions): Promise<PermissionsV2EffectiveAuthorizationConfiguration>

Route

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.

updateApprovalConfiguration(reference: PermissionsV2ApprovalRequirementReference, body: PermissionsV2AuthorizationConfigurationWrite, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationConfigurationView>

Route

PUT /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/policies/{policyId}/versions/{policyVersion}/requirements/{requirementId}/configuration

resetApprovalConfiguration

Clears configured overrides and restores the requirement’s defaults.

resetApprovalConfiguration(reference: PermissionsV2ApprovalRequirementReference, expectedRevision: number, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationConfigurationView>

Route

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.

listApprovalConfigurationHistory(reference: PermissionsV2ApprovalRequirementReference, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationConfigurationHistory>

Route

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.

getUserApprovalAssignments(authorizationScopeId: string, userId: string, options?: ParaRestCallOptions): Promise<PermissionsV2AuthoritySetView>

Route

GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/users/{userId}/assignments

listAuthorizationScopeMembers

Lists users and their assignments in an authorization scope.

listAuthorizationScopeMembers(authorizationScopeId: string, query?: PermissionsV2AuthorizationScopeMemberListOptions, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationScopeMembers>

Route

GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/members

replaceUserApprovalAssignments

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

replaceUserApprovalAssignments(authorizationScopeId: string, userId: string, body: PermissionsV2AuthoritySetWrite, options?: ParaRestCallOptions): Promise<PermissionsV2AuthoritySetView>

Route

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.

listUserApprovalAssignmentHistory(authorizationScopeId: string, userId: string, options?: ParaRestCallOptions): Promise<PermissionsV2AuthoritySetHistory>

Route

GET /v1/permissions-v2/authorization-scopes/{authorizationScopeId}/users/{userId}/assignments/history

getWalletAuthorizationScope

Reads the authorization scope currently bound to a wallet.

getWalletAuthorizationScope(walletId: string, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationScopeBindingView>

Route

GET /v1/permissions-v2/wallets/{walletId}/authorization-scope

setWalletAuthorizationScope

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

setWalletAuthorizationScope(walletId: string, body: PermissionsV2AuthorizationScopeBindingWrite, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationScopeBindingView>

Route

PUT /v1/permissions-v2/wallets/{walletId}/authorization-scope

listWalletAuthorizationScopeHistory

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

listWalletAuthorizationScopeHistory(walletId: string, query?: PermissionsV2HistoryOptions, options?: ParaRestCallOptions): Promise<PermissionsV2AuthorizationScopeBindingHistory>

Route

GET /v1/permissions-v2/wallets/{walletId}/authorization-scope/history

Approval cases

listPartnerApprovalCases

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

listPartnerApprovalCases(query?: PermissionsV2CaseListOptions, options?: ParaRestCallOptions): Promise<PermissionsV2ConditionalApprovalPartnerCaseList>

Route

GET /v1/permissions-v2/approval-cases

getPartnerApprovalCase

Reads a partner approval case without impersonating an approver.

getPartnerApprovalCase(caseId: string, options?: ParaRestCallOptions): Promise<Omit<PermissionsV2ConditionalApprovalCaseView, 'decision'>>

Route

GET /v1/permissions-v2/approval-cases/{caseId}

Usage

getPartnerPolicyUsage

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

getPartnerPolicyUsage(policyId: string, context: PermissionsV2PartnerUsageContext, options?: ParaRestCallOptions): Promise<PermissionsV2PolicyUsage>

Route

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.

​Arguments and errors

​Policy discovery

​listPartnerPolicies

​getPartnerPolicy

​listPartnerPolicyVersions

​User consent

​listUserPolicyConsents

​getUserPolicyConsent

​User parameters

​listUserAdjustablePolicies

​getUserPolicyParameters

​listUserPolicyParameterHistory

​Approval configuration

​listConfigurableApprovalRequirements

​getConfigurableApprovalRequirement

​getApprovalConfiguration

​getEffectiveApprovalConfiguration

​updateApprovalConfiguration

​resetApprovalConfiguration

​listApprovalConfigurationHistory

​Roles and wallet scopes

​getUserApprovalAssignments

​listAuthorizationScopeMembers

​replaceUserApprovalAssignments

​listUserApprovalAssignmentHistory

​getWalletAuthorizationScope

​setWalletAuthorizationScope

​listWalletAuthorizationScopeHistory

​Approval cases

​listPartnerApprovalCases

​getPartnerApprovalCase

​Usage

​getPartnerPolicyUsage

Arguments and errors

Policy discovery

listPartnerPolicies

getPartnerPolicy

listPartnerPolicyVersions

User consent

listUserPolicyConsents

getUserPolicyConsent

User parameters

listUserAdjustablePolicies

getUserPolicyParameters

listUserPolicyParameterHistory

Approval configuration

listConfigurableApprovalRequirements

getConfigurableApprovalRequirement

getApprovalConfiguration

getEffectiveApprovalConfiguration

updateApprovalConfiguration

resetApprovalConfiguration

listApprovalConfigurationHistory

Roles and wallet scopes

getUserApprovalAssignments

listAuthorizationScopeMembers

replaceUserApprovalAssignments

listUserApprovalAssignmentHistory

getWalletAuthorizationScope

setWalletAuthorizationScope

listWalletAuthorizationScopeHistory

Approval cases

listPartnerApprovalCases

getPartnerApprovalCase

Usage

getPartnerPolicyUsage