Cerbos JavaScript SDK
    Preparing search index...

    Class HTTP

    A client for interacting with the Cerbos policy decision point server over HTTP.

    This is primarily intended for use in browsers, and requires fetch to be available globally. If you're targeting old browsers, you'll need to apply a polyfill.

    You can use it in server-side Node.js applications, but the gRPC client might be more appropriate.

    See the parent class for available methods.

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Methods

    addOrUpdatePolicies addOrUpdateSchemas checkHealth checkResource checkResources deleteSchema deleteSchemas disablePolicies disablePolicy enablePolicies enablePolicy getAccessLogEntry getDecisionLogEntry getPolicies getPolicy getSchema getSchemas inspectPolicies isAllowed listAccessLogEntries listDecisionLogEntries listPolicies listSchemas planResources reloadStore serverInfo withPrincipal

    Constructors

    • Create a client for interacting with the Cerbos policy decision point (PDP) server over HTTP.

      Parameters

      • baseUrl: string

        Base Cerbos PDP server URL (the Cerbos REST API must be available at ${baseUrl}/api/).

      • options: Options = {}

        Additional client settings.

      Returns HTTP

      Connect via HTTP:

      const cerbos = new HTTP("http://localhost:3592");

      Connect to the hosted demo PDP to experiment in the playground:

      const cerbos = new HTTP("https://demo-pdp.cerbos.cloud", { playgroundInstance: "gE623b0180QlsG5a4QIN6UOZ6f3iSFW2" });

    Methods

    • Add policies, or update existing policies.

      Parameters

      Returns Promise<void>

      Requires

      Create a policy in code:

      await cerbos.addOrUpdatePolicies({
        policies: [{
          resourcePolicy: {
            resource: "document",
            version: "1",
            rules: [{
              actions: ["*"],
              effect: Effect.ALLOW,
              roles: ["ADMIN"],
            }],
          },
        }],
      });

      Load a policy from a YAML or JSON file with readPolicy:

      import { readPolicy } from "@cerbos/files";

      await cerbos.addOrUpdatePolicies({
        policies: [await readPolicy("path/to/policy.yaml")],
      });

      Load policies and schemas from a directory with readDirectory:

      import { readDirectory } from "@cerbos/files";

      const { policies, schemas } = await readDirectory("path/to/directory");

      await cerbos.addOrUpdateSchemas({ schemas });
      await cerbos.addOrUpdatePolicies({ policies });

    • Add schemas to be used for validating principal or resource attributes, or update existing schemas.

      Parameters

      Returns Promise<void>

      Requires

      Create a schema in code:

      await cerbos.addOrUpdateSchemas({
        schemas: [{
          id: "document.json",
          definition: {
            type: "object",
            properties: {
              owner: { type: "string" }
            }
          },
        }],
      });

      Load a schema from a JSON file with readSchema:

      import { readSchema } from "@cerbos/files";

      await cerbos.addOrUpdateSchemas({
        schemas: [await readSchema("_schemas/path/to/schema.json")],
      });

      Load policies and schemas from a directory with readDirectory:

      import { readDirectory } from "@cerbos/files";

      const { policies, schemas } = await readDirectory("path/to/directory");

      await cerbos.addOrUpdateSchemas({ schemas });
      await cerbos.addOrUpdatePolicies({ policies });

    • Check a principal's permissions on a set of resources.

      Parameters

      Returns Promise<CheckResourcesResponse>

      const decision = await cerbos.checkResources({
        principal: {
          id: "user@example.com",
          roles: ["USER"],
          attr: { tier: "PREMIUM" },
        },
        resources: [
          {
            resource: {
              kind: "document",
              id: "1",
              attr: { owner: "user@example.com" },
            },
            actions: ["view", "edit"],
          },
          {
            resource: {
              kind: "image",
              id: "1",
              attr: { owner: "user@example.com" },
            },
            actions: ["delete"],
          },
        ],
      });

      decision.isAllowed({
        resource: { kind: "document", id: "1" },
        action: "view",
      }); // => true

    • Delete a schema.

      Parameters

      Returns Promise<boolean>

      Requires

      The way this method handles failure depends on the version of the connected PDP server. When the server is running Cerbos v0.25 or later, it returns true if the schema was deleted and false if the schema was not found. With earlier versions of Cerbos, it throws an error if the schema was not found, and returns successfully if the schema was deleted; the returned value should be ignored.

      const deleted = await cerbos.deleteSchema("document.json");

    • Check if a principal is allowed to perform an action on a resource.

      Parameters

      Returns Promise<boolean>

      await cerbos.isAllowed({
        principal: {
          id: "user@example.com",
          roles: ["USER"],
          attr: { tier: "PREMIUM" },
        },
        resource: {
          kind: "document",
          id: "1",
          attr: { owner: "user@example.com" },
        },
        action: "view",
      }); // => true

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods