Permissions hooks

React query and mutation hooks for Permissions

Import these hooks from @getpara/react-sdk, @getpara/react-sdk-lite or @getpara/react-native-wallet, and call them inside your Para provider. Each hook wraps a Para client method and keeps its access rules and Portal behavior. The link under each hook goes to that method.

Errors

A query hook reports a failed request in error; a mutation rejects from its Async function and sets error. The error is the one the client method throws, described on each method page. A mutation called without a Para client fails with no para instance, and one called before the user is fully logged in fails with User must be authenticated. Permissions errors lists every server error.

Query hooks

Query hooks take the same positional arguments as their client method. They return TanStack Query UseQueryResult<Result, Error> with data, error, isPending, and refetch. Public discovery runs when a client exists; other queries wait for a fully authenticated user.

import { useApplicablePolicies } from "@getpara/react-sdk";

const { data, isPending, error } = useApplicablePolicies({ walletId });
const policies = data?.policies;

usePolicies

Lists your app's active policies that do not target specific users or wallets.

usePolicies(): UseQueryResult<PermissionsV2PolicyListResponse, Error>

Arguments, result, and access requirements.

usePolicy

Reads the active version of a policy that does not target specific users or wallets.

usePolicy(policyId: string): UseQueryResult<PermissionsV2PolicyResponse, Error>

Arguments, result, and access requirements.

useApplicablePolicies

Lists the active policies that apply to a wallet of the signed-in user.

useApplicablePolicies(context: PermissionsV2WalletContext): UseQueryResult<PermissionsV2PolicyListResponse, Error>

Arguments, result, and access requirements.

useApplicablePolicy

Reads one active policy that applies to a wallet of the signed-in user.

useApplicablePolicy(policyId: string, context: PermissionsV2WalletContext): UseQueryResult<PermissionsV2PolicyResponse, Error>

Arguments, result, and access requirements.

useUserPolicyConsents

Lists the consent requests for a wallet of the signed-in user, with the status of each.

useUserPolicyConsents(context: PermissionsV2ConsentListContext): UseQueryResult<PermissionsV2DelegationConsentDiscoveryResponse, Error>

Arguments, result, and access requirements.

useUserPolicyConsent

Reads the consent status of one policy for a wallet of the signed-in user.

useUserPolicyConsent(policyId: string, context: PermissionsV2WalletContext): UseQueryResult<PermissionsV2DelegationConsentView, Error>

Arguments, result, and access requirements.

useUserAdjustablePolicies

Lists the policies whose parameters the signed-in user can adjust, with the user's current values.

useUserAdjustablePolicies(): UseQueryResult<PermissionsV2UserAdjustablePolicyListResponse, Error>

Arguments, result, and access requirements.

useUserPolicyParameters

Reads the signed-in user's values for one policy's adjustable parameters, with the declarations and current revision.

useUserPolicyParameters(policyId: string): UseQueryResult<PermissionsV2UserParameterView, Error>

Arguments, result, and access requirements.

useUserPolicyParameterHistory

Lists the saved revisions of the signed-in user's values for one policy, newest first.

useUserPolicyParameterHistory(policyId: string, options?: PermissionsV2HistoryOptions): UseQueryResult<PermissionsV2UserParameterHistory, Error>

Arguments, result, and access requirements.

useConfigurableApprovalRequirements

Lists the approval requirements the signed-in user can configure in an authorization scope.

useConfigurableApprovalRequirements(authorizationScopeId: string): UseQueryResult<PermissionsV2ConditionalRequirementList, Error>

Arguments, result, and access requirements.

useConfigurableApprovalRequirement

Reads one approval requirement the signed-in user can configure, in a specific policy version.

useConfigurableApprovalRequirement(reference: PermissionsV2ApprovalRequirementReference): UseQueryResult<PermissionsV2ConditionalRequirementView, Error>

Arguments, result, and access requirements.

useApprovalConfiguration

Reads the stored settings and revision for an approval requirement in an authorization scope.

useApprovalConfiguration(reference: PermissionsV2ApprovalRequirementReference): UseQueryResult<PermissionsV2AuthorizationConfigurationView, Error>

Arguments, result, and access requirements.

useEffectiveApprovalConfiguration

Reads an approval requirement with the stored settings for an authorization scope applied.

useEffectiveApprovalConfiguration(reference: PermissionsV2ApprovalRequirementReference): UseQueryResult<PermissionsV2EffectiveAuthorizationConfiguration, Error>

Arguments, result, and access requirements.

useApprovalConfigurationHistory

Lists every stored revision of an approval requirement's settings in an authorization scope, newest first.

useApprovalConfigurationHistory(reference: PermissionsV2ApprovalRequirementReference): UseQueryResult<PermissionsV2AuthorizationConfigurationHistory, Error>

Arguments, result, and access requirements.

useUserApprovalAssignments

Reads the signed-in user's roles and attributes in an authorization scope.

useUserApprovalAssignments(authorizationScopeId: string): UseQueryResult<PermissionsV2AuthoritySetView, Error>

Arguments, result, and access requirements.

useUserApprovalCapabilities

Lists the approval requirements the signed-in user can configure in an authorization scope.

useUserApprovalCapabilities(authorizationScopeId: string): UseQueryResult<PermissionsV2AuthorizationScopeCapabilities, Error>

Arguments, result, and access requirements.

useAccessibleApprovalCases

Lists the approval cases the signed-in user can review, and the signature collections they started.

useAccessibleApprovalCases(): UseQueryResult<{ cases: PermissionsV2ConditionalApprovalCaseView[] }, Error>

Arguments, result, and access requirements.

useAccessibleApprovalCase

Reads an approval case the signed-in user can review, with the user's decision options.

useAccessibleApprovalCase(caseId: string): UseQueryResult<PermissionsV2ConditionalApprovalCaseView, Error>

Arguments, result, and access requirements.

useInitiatedApprovalCases

Lists the approval cases for requests the signed-in user started, newest first.

useInitiatedApprovalCases(options?: PermissionsV2CaseListOptions): UseQueryResult<PermissionsV2ConditionalApprovalCaseList, Error>

Arguments, result, and access requirements.

useInitiatedApprovalCase

Reads an approval case for a request the signed-in user started.

useInitiatedApprovalCase(caseId: string): UseQueryResult<PermissionsV2ConditionalApprovalCaseView, Error>

Arguments, result, and access requirements.

useApprovalSigningPayload

Reads what the signed-in approver signs in the current stage of a signature collection.

useApprovalSigningPayload(caseId: string): UseQueryResult<PermissionsV2ApprovalSigningPayload, Error>

Arguments, result, and access requirements.

useApprovalSignatures

Reads the collected signatures once a signature collection is complete.

useApprovalSignatures(caseId: string): UseQueryResult<PermissionsV2ApprovalSignatures, Error>

Arguments, result, and access requirements.

useUserPolicyUsage

Reads the current spend usage of a policy for a wallet of the signed-in user.

useUserPolicyUsage(policyId: string, context: PermissionsV2UsageContext): UseQueryResult<PermissionsV2PolicyUsage, Error>

Arguments, result, and access requirements.

Mutation hooks

Mutation hooks take no arguments. The returned functions are named after the client method: method(variables) starts a mutation and methodAsync(variables) returns its promise. Results also include data, error, isPending, and reset. Successful writes invalidate the current user’s permissions queries; generating a Portal URL does not.

import { useGetPolicyConsentUrl } from "@getpara/react-sdk";

const { getPolicyConsentUrlAsync, isPending } = useGetPolicyConsentUrl();
const url = await getPolicyConsentUrlAsync({ walletId, policyId });
window.open(url, "_blank");

useUpdateUserPolicyParameters

Saves the signed-in user's values for a policy's adjustable parameters.

const { updateUserPolicyParameters, updateUserPolicyParametersAsync, data, error, isPending, reset } = useUpdateUserPolicyParameters();
// Mutation variables: { policyId: string; body: PermissionsV2UserParameterSave }
// updateUserPolicyParametersAsync returns Promise<PermissionsV2UserParameterView>.

Arguments, result, and access requirements.

useResetUserPolicyParameters

Restores the policy defaults as the signed-in user's values for its adjustable parameters.

const { resetUserPolicyParameters, resetUserPolicyParametersAsync, data, error, isPending, reset } = useResetUserPolicyParameters();
// Mutation variables: { policyId: string; body: PermissionsV2UserParameterReset }
// resetUserPolicyParametersAsync returns Promise<PermissionsV2UserParameterView>.

Arguments, result, and access requirements.

useUpdateApprovalConfiguration

Saves new values for an approval requirement's configurable settings in an authorization scope.

const { updateApprovalConfiguration, updateApprovalConfigurationAsync, data, error, isPending, reset } = useUpdateApprovalConfiguration();
// Mutation variables: { reference: PermissionsV2ApprovalRequirementReference; body: PermissionsV2AuthorizationConfigurationWrite }
// updateApprovalConfigurationAsync returns Promise<PermissionsV2AuthorizationConfigurationView>.

Arguments, result, and access requirements.

useResetApprovalConfiguration

Clears the stored settings for an approval requirement so the authored defaults apply again.

const { resetApprovalConfiguration, resetApprovalConfigurationAsync, data, error, isPending, reset } = useResetApprovalConfiguration();
// Mutation variables: { reference: PermissionsV2ApprovalRequirementReference; expectedRevision: number; force?: boolean }
// resetApprovalConfigurationAsync returns Promise<PermissionsV2AuthorizationConfigurationView>.

Arguments, result, and access requirements.

useApproveApprovalCase

Records the signed-in approver's approval on an approval case.

const { approveApprovalCase, approveApprovalCaseAsync, data, error, isPending, reset } = useApproveApprovalCase();
// Mutation variables: string
// approveApprovalCaseAsync returns Promise<PermissionsV2ConditionalApprovalCaseView>.

Arguments, result, and access requirements.

useRejectApprovalCase

Records the signed-in approver's rejection, which ends the approval case.

const { rejectApprovalCase, rejectApprovalCaseAsync, data, error, isPending, reset } = useRejectApprovalCase();
// Mutation variables: string
// rejectApprovalCaseAsync returns Promise<PermissionsV2ConditionalApprovalCaseView>.

Arguments, result, and access requirements.

useCancelApprovalCase

Cancels a pending approval case for a request the signed-in user started.

const { cancelApprovalCase, cancelApprovalCaseAsync, data, error, isPending, reset } = useCancelApprovalCase();
// Mutation variables: string
// cancelApprovalCaseAsync returns Promise<PermissionsV2ConditionalApprovalCaseView>.

Arguments, result, and access requirements.

useCreateApprovalSignatureCollection

Opens an approval case that collects approvers' signatures for a transaction.

const { createApprovalSignatureCollection, createApprovalSignatureCollectionAsync, data, error, isPending, reset } = useCreateApprovalSignatureCollection();
// Mutation variables: PermissionsV2TransactionSignatureCollection
// createApprovalSignatureCollectionAsync returns Promise<PermissionsV2ApprovalSignatureCollectionResult>.

Arguments, result, and access requirements.

useSubmitApprovalSignature

Submits the signed-in approver's signature to a signature collection.

const { submitApprovalSignature, submitApprovalSignatureAsync, data, error, isPending, reset } = useSubmitApprovalSignature();
// Mutation variables: { caseId: string; body: PermissionsV2ConditionalApprovalSignature }
// submitApprovalSignatureAsync returns Promise<PermissionsV2ConditionalApprovalCaseView>.

Arguments, result, and access requirements.

useSignApprovalTransaction

Signs a signature collection's payload with one of the signed-in approver's wallets and submits the signature.

const { signApprovalTransaction, signApprovalTransactionAsync, data, error, isPending, reset } = useSignApprovalTransaction();
// Mutation variables: SignApprovalTransactionParams
// signApprovalTransactionAsync returns Promise<PermissionsV2ConditionalApprovalCaseView>.

Arguments, result, and access requirements.

useGetPolicyConsentUrl

Builds the Portal URL where the signed-in user reviews a policy and consents to it.

const { getPolicyConsentUrl, getPolicyConsentUrlAsync, data, error, isPending, reset } = useGetPolicyConsentUrl();
// Mutation variables: { walletId: string; policyId: string }
// getPolicyConsentUrlAsync returns Promise<string>.

Arguments, result, and access requirements.

useGetApprovalCaseReviewUrl

Builds the Portal URL where the signed-in approver reviews an approval case.

const { getApprovalCaseReviewUrl, getApprovalCaseReviewUrlAsync, data, error, isPending, reset } = useGetApprovalCaseReviewUrl();
// Mutation variables: { caseId: string }
// getApprovalCaseReviewUrlAsync returns Promise<string>.

Arguments, result, and access requirements.