React SDK

We offer a React SDK for interacting with the Permissions API. The React SDK brings Hooks and other React specific concepts for the Space Blocks Permissions service.

Getting started

The React SDK is designed for use in React applications. It can be used to check permissions for your actions.

Installation

Add the Permissions React SDK NPM package to our project.

NPM

npm install @spaceblocks/permissions-react

Yarn

yarn add @spaceblocks/permissions-react

Initialization

Before using the React SDK, you need to implement the Frontend Access Token Flow at your server, to expose an endpoint that can be used to request an Impersonated Access Token for your frontend services.

Instantiate the SDK with the API URL and API Key from the Developer Portal and pass an accessTokenProvider function, which calls your backend and returns an Impersonated Space Blocks Access Token. Besides that, you need to pass a currentSubjectIdProvider function, which returns the current subject id (normally the current user id).

Best practice is to wrap your application with the PermissionsProvider component. This ensures that all hooks and components have access to the PermissionsClient.

import { PermissionsProvider } from '@spaceblocks/permissions-react';

function App {
  const accessTokenProvider = () => {
    // this function calls Your backend to get the access token
    return '<YOUR_IMPERSONATED_ACCESS_TOKEN>';
  };

  const currentSubjectIdProvider = () => {
    // this function returns the current subject id (normally the current user id)
    return '<CURRENT_USER_ID>';
  };

  return (
    <PermissionsProvider
      currentSubjectIdProvider={currentSubjectIdProvider}
      url="<YOUR_PERMISSIONS_URL>"
      apiKey="<YOUR_API_KEY>"
      accessTokenProvider={accessTokenProvider}
    >
      <App />
    </PermissionsProvider>
  );
};

Hooks

The React SDK provides a set of hooks to interact with the Permissions API. The hooks are designed to be used in React function components. The hooks are based on the JavaScript Client SDK and provide a more React specific interface.

usePermissionsClient

The usePermissionsClient hook returns the PermissionsClient instance. This can be used to call the Permissions API directly.

import { usePermissionsClient } from '@spaceblocks/permissions-react';

const permissionsClient = usePermissionsClient();

useMembers

For current tenant

The useMembers hook returns the members of the current tenant, which is the tenant from the impersonated access token. It also returns a loading state, which indicates if the members are currently being loaded.

import { useMembers } from '@spaceblocks/permissions-react';

const { members, isLoading } = useMembers();

// use the members somewhere
const rolesOfAlice = members.subjects['alice'];

For a resource

The useMembers hook returns a list of members for a given resource, when a resourceTypeId and resourceId are passed. It also returns a loading state, which indicates if the members are currently being loaded.

import { useMembers } from '@spaceblocks/permissions-react';

const { members, isLoading } = useMembers('<RESOURCE_TYPE_ID>', '<RESOURCE_ID>');

// use the members somewhere
const rolesOfAlice = members.subjects['alice'];

useUpsertMembers

For current tenant

The useUpsertMembers hook returns a function to upsert members for the current tenant. It also returns a loading state, which indicates that the members are currently being upserted.

import { useUpsertMembers } from '@spaceblocks/permissions-react';

const { upsertMembersAsync, isLoading } = useUpsertMembers();

// call the function somewhere
upsertMembersAsync(
  {
    'subject-a': ['role-a', 'role-b'],
    'subject-b': ['role-c']
  },
  {
    'group-a': ['role-a', 'role-b']
  }
);

For a resource

The useUpsertMembers hook returns a function to upsert members for a given resource, when a resourceTypeId and resourceId are passed. It also returns a loading state, which indicates that the members are currently being upserted.

import { useUpsertMembers } from '@spaceblocks/permissions-react';

const { upsertMembersAsync, isLoading } = useUpsertMembers('<RESOURCE_TYPE_ID>', '<RESOURCE_ID>');

// call the function somewhere
upsertMembersAsync(
  {
    'subject-a': ['role-a', 'role-b'],
    'subject-b': ['role-c']
  },
  {
    'group-a': ['role-a', 'role-b']
  }
);

useDeleteMembers

For current tenant

The useDeleteMembers hook returns a function to delete members for the current tenant. It also returns a loading state, which indicates that the members are currently being deleted.

import { useDeleteMembers } from '@spaceblocks/permissions-react';

const { deleteMembersAsync, isLoading } = useDeleteMembers();

// call the function somewhere
deleteMembersAsync(['subject-a', 'subject-b'], ['group-a']);

For a resource

The useDeleteMembers hook returns a function to delete members for a given resource, when a resourceTypeId and resourceId are passed. It also returns a loading state, which indicates that the members are currently being deleted.

import { useDeleteMembers } from '@spaceblocks/permissions-react';

const { deleteMembersAsync, isLoading } = useDeleteMembers('<RESOURCE_TYPE_ID>', '<RESOURCE_ID>');

// call the function somewhere
deleteMembersAsync(['subject-a', 'subject-b'], ['group-a']);

useRoles

The useRoles hook returns all available roles no matter if they are Build-in or User-defined roles. It also returns a loading state, which indicates if the roles are currently being loaded.

import { useRoles } from '@spaceblocks/permissions-react';

const { roles, isLoading } = useRoles();

useCreateRole

The useCreateRole hook returns a function to create a User-defined role. It also returns a loading state, which indicates that the role is currently being created.

import { useCreateRole } from '@spaceblocks/permissions-react';

const { createRoleAsync, isLoading } = useCreateRole();

// call the function somewhere
createRoleAsync({
  name: 'my-role',
  permissions: {
    tenant: ['permission-a', 'permission-b'],
    'resource-type-a': ['permission-a', 'permission-b']
  }
});

useUpdateRole

The useUpdateRole hook returns a function to update the User-defined role with the given roleId. It also returns a loading state, which indicates that the role is currently being updated.

import { useUpdateRole } from '@spaceblocks/permissions-react';

const { updateRoleAsync, isLoading } = useUpdateRole('ROLE_ID');

// call the function somewhere
updateRoleAsync({
  name: 'my-role',
  permissions: {
    tenant: ['permission-x', 'permission-b'],
    'resource-type-a': ['permission-x', 'permission-b']
  }
});

useDeleteRole

The useDeleteRole hook returns a function to delete a User-defined role. It also returns a loading state, which indicates that the role is currently being deleted.

import { useDeleteRole } from '@spaceblocks/permissions-react';

const { deleteRoleAsync, isLoading } = useDeleteRole();

// call the function somewhere
deleteRoleAsync('ROLE_ID');