### Install Topaz via Go

Source: https://www.topaz.sh/docs/getting-started

Installs the Topaz CLI using the Go programming language's install command. This method requires Go to be installed on the system.

```go
go install github.com/aserto-dev/topaz/cmd/topaz@latest  

```

--------------------------------

### Clone and Install Node.js Server

Source: https://www.topaz.sh/docs/getting-started/samples/node

Commands to retrieve the server source code from GitHub and install the required project dependencies using Yarn.

```bash
git clone https://github.com/aserto-demo/todo-node-js-v2
yarn
```

--------------------------------

### Install Todo Template

Source: https://www.topaz.sh/docs/getting-started

Installs the 'todo' template for Topaz, which includes a sample authorization policy, domain model, and data. This command uses the Topaz CLI.

```bash
topaz templates install todo  

```

--------------------------------

### Start the Node.js Server

Source: https://www.topaz.sh/docs/getting-started/samples/node

Command to launch the Node.js application server after configuration is complete.

```bash
yarn start
```

--------------------------------

### Start Flask Development Server

Source: https://www.topaz.sh/docs/getting-started/samples/flask

Command to launch the Flask application using the pipenv environment. This starts the server locally for testing and development.

```bash
pipenv run flask run
```

--------------------------------

### Create a Sample Policy using 'policy' CLI

Source: https://www.topaz.sh/docs/policies/lifecycle

Generates a basic 'hello world' policy using the 'policy templates apply' command. This command creates a minimal policy structure, including Rego files and a manifest, suitable for getting started.

```bash
policy templates apply policy-template  

```

--------------------------------

### Display Topaz Configuration Directory Structure

Source: https://www.topaz.sh/docs/getting-started

Shows the directory structure of the Topaz configuration files after installing the 'todo' template. This helps in locating configuration files like `todo.yaml`.

```bash
tree $HOME/.config/topaz  

```

--------------------------------

### Install Topaz via Homebrew

Source: https://www.topaz.sh/docs/getting-started

Installs Topaz using Homebrew on macOS or LinuxBrew for Linux. This is a convenient method for users who manage their packages with Homebrew.

```bash
brew install --cask aserto-dev/tap/topaz  

```

--------------------------------

### GET /api/v2/policies

Source: https://www.topaz.sh/docs/getting-started

Retrieves the list of policies currently loaded into the Topaz authorizer.

```APIDOC
## GET /api/v2/policies

### Description
Retrieves the set of policies that Topaz has loaded.

### Method
GET

### Endpoint
https://localhost:8383/api/v2/policies

### Response
#### Success Response (200)
- **policies** (array) - List of loaded policy objects

#### Response Example
{
  "policies": [
    {
      "id": "todoApp",
      "version": "1.0.0"
    }
  ]
}
```

--------------------------------

### Install Topaz via WinGet

Source: https://www.topaz.sh/docs/getting-started

Installs Topaz using WinGet on Windows 10+. This is the recommended method for Windows users to install Topaz.

```powershell
winget install Aserto.Topaz  

```

--------------------------------

### Configure Environment Variables

Source: https://www.topaz.sh/docs/getting-started/samples/flask

Instructions for creating the .env file from the example template. This file is essential for configuring the connection to the Aserto authorizer and directory services.

```bash
cp .env.example .env
```

```text
JWKS_URI=https://citadel.demo.aserto.com/dex/keys
ISSUER=https://citadel.demo.aserto.com/dex
AUDIENCE=citadel-app

ASERTO_POLICY_ROOT="todoApp"

ASERTO_AUTHORIZER_SERVICE_URL=localhost:8282
ASERTO_AUTHORIZER_CERT_PATH=$HOME/.local/share/topaz/certs/grpc-ca.crt
ASERTO_DIRECTORY_SERVICE_URL=localhost:9292
ASERTO_DIRECTORY_GRPC_CERT_PATH=$HOME/.local/share/topaz/certs/grpc-ca.crt
```

--------------------------------

### Execute Topaz daemon

Source: https://www.topaz.sh/docs/deployment/binary

Starts the Topaz daemon using the generated configuration file. It requires setting the TOPAZ_DIR environment variable to point to the configuration directory.

```bash
TOPAZ_DIR=$HOME/.config/topaz ./topazd run -c $HOME/.config/topaz/cfg/todo.yaml
```

--------------------------------

### Display Topaz Data Directory Structure

Source: https://www.topaz.sh/docs/getting-started

Shows the directory structure of the Topaz data files after installing the 'todo' template. This includes generated certificates, the embedded database, and template artifacts.

```bash
tree $HOME/.local/share/topaz  

```

--------------------------------

### Start the Todo Application

Source: https://www.topaz.sh/docs/getting-started/samples/test-application

Starts the Todo web application using the 'yarn start' command. After running this, the application will be accessible via a web browser on 'localhost:3000'.

```bash
yarn start  
```

--------------------------------

### Install and verify custom plugins

Source: https://www.topaz.sh/docs/command-line-interface/ds-load-cli/plugins/custom

Demonstrates how to verify the installation of a custom plugin binary in the designated directory and how to confirm its availability via the ds-load command-line interface.

```bash
ls -l ~/.ds-load/plugins

ds-load exec --help
```

--------------------------------

### Installation

Source: https://www.topaz.sh/docs/software-development-kits/javascript/express

Install the Aserto Node.js SDK using npm or yarn.

```APIDOC
## Installation

Using npm:
```
npm install @aserto/aserto-node
```

Using yarn:
```
yarn add @aserto/aserto-node
```
```

--------------------------------

### Clone and Install Python Flask Application

Source: https://www.topaz.sh/docs/getting-started/samples/flask

Commands to clone the todo-python-v2 repository from GitHub and install the required project dependencies using pipenv. Ensure pipenv is installed on your system before executing these commands.

```bash
git clone https://github.com/aserto-demo/todo-python-v2
cd todo-python-v2
pipenv install
```

--------------------------------

### Install Topaz Authorizer Container Image

Source: https://www.topaz.sh/docs/getting-started

Pulls the latest Topaz authorizer Docker container image. This command requires Docker to be installed and running on the system.

```bash
topaz install  

```

--------------------------------

### Install Topaz CLI via Go

Source: https://www.topaz.sh/docs/command-line-interface/topaz-cli

Installs the Topaz CLI using the Go programming language's install command. This method requires Go to be installed and configured on the system.

```go
go install github.com/aserto-dev/topaz/cmd/topaz@latest
```

--------------------------------

### Configure Environment Variables

Source: https://www.topaz.sh/docs/getting-started/samples/node

Commands to initialize the .env file and a sample configuration for connecting the application to Aserto services.

```bash
cp .env.example .env
```

```text
JWKS_URI=https://citadel.demo.aserto.com/dex/keys
ISSUER=https://citadel.demo.aserto.com/dex
AUDIENCE=citadel-app

ASERTO_POLICY_ROOT=todoApp

ASERTO_AUTHORIZER_SERVICE_URL=localhost:8282
ASERTO_DIRECTORY_SERVICE_URL=localhost:9292
ASERTO_DIRECTORY_REJECT_UNAUTHORIZED=false

ASERTO_GRPC_CA_CERT_PATH=${HOME}/.local/share/topaz/certs/grpc-ca.crt
```

--------------------------------

### Install flask-aserto package

Source: https://www.topaz.sh/docs/software-development-kits/python/flask

Installation commands for the flask-aserto library using common Python package managers.

```bash
pip install -U flask-aserto
```

```bash
poetry add flask-aserto
```

--------------------------------

### Install Application Dependencies with Yarn

Source: https://www.topaz.sh/docs/getting-started/samples/test-application

Navigates into the 'todo-application' directory and installs project dependencies using Yarn. This command is essential after cloning the repository.

```bash
cd todo-application  
yarn  
```

--------------------------------

### Install Topaz SDK

Source: https://www.topaz.sh/docs/software-development-kits/javascript/express

Commands to install the @aserto/aserto-node package using common Node.js package managers.

```bash
npm install @aserto/aserto-node
```

```bash
yarn add @aserto/aserto-node
```

--------------------------------

### Interact with Directory gRPC Endpoint

Source: https://www.topaz.sh/docs/getting-started

This snippet demonstrates how to interact with the Topaz directory endpoint using gRPC. It requires the installation of 'grpcui' or 'grpcurl' and points them to localhost:9292.

```shell
grpcui --insecure localhost:9292
```

--------------------------------

### Install Aserto SPA SDK

Source: https://www.topaz.sh/docs/software-development-kits/javascript/spa

Commands to install the Aserto SPA SDK package using common JavaScript package managers.

```bash
npm install @aserto/aserto-spa-js
```

```bash
yarn add @aserto/aserto-spa-js
```

--------------------------------

### Install aserto-idp package

Source: https://www.topaz.sh/docs/software-development-kits/python/identity-providers

Instructions for installing the aserto-idp package using common Python dependency managers. Choose between pip or Poetry based on your project configuration.

```bash
pip install aserto-idp
```

```bash
poetry add aserto-idp
```

--------------------------------

### Install Aserto Middleware Package

Source: https://www.topaz.sh/docs/software-development-kits/dotnet/dotnetcorecheck

Commands to install the Aserto ASP.NET Core middleware via NuGet Package Manager or the .NET CLI.

```powershell
Install-Package Aserto.AspNetCore.Middleware
```

```bash
dotnet add package Aserto.AspNetCore.Middleware
```

--------------------------------

### Application Properties Example for Aserto Configuration

Source: https://www.topaz.sh/docs/software-development-kits/java/middleware

This is an example of an `application.properties` file demonstrating various configuration parameters for the Aserto middleware. It includes settings for connecting to both local Topaz instances and Aserto's hosted authorizer service.

```properties
# --- Authorizer configuration
aserto.authorizer.serviceUrl=localhost:8282
aserto.authorization.enabled=false
aserto.authorizer.policyRoot=todoApp
aserto.authorizer.decision=allowed

## Topaz
##  This configuration targets a Topaz instance running locally.
aserto.authorizer.insecure=false
aserto.authorizer.grpc.caCertPath=${user.home}/.local/share/topaz/certs/grpc-ca.crt

## Aserto hosted authorizer
#aserto.tenantId=<tenant_id>
#aserto.authorizer.policyName=todo
#aserto.authorizer.policyLabel=todo
#aserto.authorizer.apiKey=<api_key>
```

--------------------------------

### Topaz configuration file schema

Source: https://www.topaz.sh/docs/command-line-interface/topaz-cli/configuration

An annotated YAML configuration example for Topaz, demonstrating the structure for logging, directory paths, and remote directory settings.

```yaml
# yaml-language-server: $schema=https://topaz.sh/schema/config.json
---
# config schema version
version: 2

logging:
  prod: true
  log_level: info

directory:
  db_path: ${TOPAZ_DB_DIR}/directory.db
  request_timeout: 5s
  seed_metadata: false

# remote directory is used to resolve the identity for the authorizer.
remote_directory:
  address: "0.0.0.0:9292"
  insecure: true
```

--------------------------------

### Install Topaz CLI via Homebrew

Source: https://www.topaz.sh/docs/command-line-interface/topaz-cli

Installs the Topaz CLI on macOS or Linux using Homebrew. This is a convenient method for managing CLI installations on Unix-like systems.

```bash
brew install --cask aserto-dev/tap/topaz
```

--------------------------------

### LDAP Plugin Configuration Example

Source: https://www.topaz.sh/docs/command-line-interface/ds-load-cli/plugins/ldap

Provides a sample configuration file for the LDAP plugin, illustrating how to set connection parameters and filters.

```APIDOC
## LDAP Plugin Configuration Example

### Description
This section presents a sample YAML configuration file demonstrating how to configure the LDAP plugin for connecting to an LDAP directory and specifying data retrieval parameters.

### Method
Configuration File

### Endpoint
N/A (Configuration file for `ds-load-ldap`)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
```yaml
---
host: "directory.prod.aserto.com:8443"
api-key: "<your-directory-api-key>"
tenant-id: "<your-tenant-id>"
ldap:
  base-dn: "dc=aserto,dc=com"
  user: "CN=aserto,CN=Users,DC=aserto,DC=com"
  password: "<ldap-user-password>"
  host: "ldap://localhost:1389"
  user-filter: "(&(objectClass=organizationalPerson))"
  group-filter: "(&(objectClass=group))"
  id-field: "objectGUID"
```

### Request Example
```yaml
---
host: "directory.prod.aserto.com:8443"
api-key: "<your-directory-api-key>"
tenant-id: "<your-tenant-id>"
ldap:
  base-dn: "dc=aserto,dc=com"
  user: "CN=aserto,CN=Users,DC=aserto,DC=com"
  password: "<ldap-user-password>"
  host: "ldap://localhost:1389"
  user-filter: "(&(objectClass=organizationalPerson))"
  group-filter: "(&(objectClass=group))"
  id-field: "objectGUID"
```

### Response
N/A (This is a configuration example, not an API response.)
```

--------------------------------

### Full Aserto Rails Configuration Example

Source: https://www.topaz.sh/docs/software-development-kits/ruby/rails

A comprehensive example of configuring the aserto-rails gem, including enabling the service, setting policy details, authorizer credentials, service URL, certificate path, decision, logger, and identity mapping.

```ruby
# config/initializers/aserto.rb  
require "aserto/rails"  

Aserto.configure do |config|  
  config.enabled = true  
  config.policy_name = "my-policy-name"  
  config.instance_label = "my-instance"  
  config.authorizer_api_key = Rails.application.credentials.aserto[:authorizer_api_key]  
  config.policy_root = "peoplefinder"  
  config.service_url = "localhost:8282"  
  config.cert_path = "/path/to/topaz/cert.crt"  
  config.decision = "allowed"  
  config.logger = Rails.logger  
  config.identity_mapping = {  
    type: :sub,  
    from: :sub  
  }  
end
```

--------------------------------

### Configure Topaz Installation Options

Source: https://www.topaz.sh/docs/command-line-interface/topaz-cli/versioning

The install command supports various flags to customize the container registry, image name, tag, and platform. These options can also be set via environment variables.

```shell
topaz install --container-registry="ghcr.io/aserto-dev" --container-image="topaz" --container-tag="latest" --container-platform="linux/arm64"
```

--------------------------------

### Install Topaz CLI via WinGet

Source: https://www.topaz.sh/docs/command-line-interface/topaz-cli

Installs the Topaz CLI on Windows 10+ using the Windows Package Manager (WinGet). This is the recommended method for Windows users.

```powershell
winget install Aserto.Topaz
```

--------------------------------

### Install Aserto React SDK using npm

Source: https://www.topaz.sh/docs/software-development-kits/javascript/react

Installs the Aserto React SDK using the npm package manager. This is the first step to integrating Aserto's permission management into your React application.

```bash
npm install @aserto/aserto-react  

```

--------------------------------

### Install Aserto Ruby Gem

Source: https://www.topaz.sh/docs/software-development-kits/ruby/middleware

Commands to install the Aserto gem via Gemfile or command line.

```ruby
gem "aserto"
```

```shell
bundle install
```

```shell
gem install aserto
```

--------------------------------

### Install Aserto React SDK using yarn

Source: https://www.topaz.sh/docs/software-development-kits/javascript/react

Installs the Aserto React SDK using the yarn package manager. This command adds the necessary package to your project's dependencies.

```bash
yarn add @aserto/aserto-react  

```

--------------------------------

### Configure and Run Topaz with a Policy

Source: https://www.topaz.sh/docs/policies/lifecycle

Configures Topaz to use a specific policy image and then starts the Topaz runtime. The 'topaz config new' command registers the policy, and 'topaz run' or 'topaz start' initiates the Topaz service.

```bash
topaz config new -d -r my-org/my-policy:v0.1.2 -n my-policy  

```

```bash
topaz run   

```

```bash
topaz start   

```

--------------------------------

### Install Aserto Java Dependency

Source: https://www.topaz.sh/docs/software-development-kits/java/authorizer

Add the Aserto Java SDK to your project using Maven. This dependency provides the necessary classes for interacting with the Aserto authorization API.

```xml
<dependency>
    <groupId>com.aserto</groupId>
    <artifactId>aserto-java</artifactId>
    <version>1.0.1</version>
</dependency>
```

--------------------------------

### Extract Topaz binary archive

Source: https://www.topaz.sh/docs/deployment/binary

Unzips the downloaded Topaz archive to extract the CLI tool and the daemon binary.

```bash
unzip topaz.zip
```

--------------------------------

### Initialize Authorizer Client in Go

Source: https://www.topaz.sh/docs/software-development-kits/go/authorizer

Demonstrates how to instantiate a new AuthorizerClient using the aserto-dev/go-aserto package. It requires specifying the address and security configuration for the connection.

```go
import (
	"github.com/aserto-dev/go-aserto"
	"github.com/aserto-dev/go-aserto/az"
)

azClient, err := az.New(
	aserto.WithAddr("localhost:8282"),
	aserto.WithInsecure(true),
)
```

--------------------------------

### Create HTTP Middleware with net/http

Source: https://www.topaz.sh/docs/software-development-kits/go/middleware-http

Demonstrates creating an authorizer client and initializing HTTP middleware for the standard net/http package. It requires an authorizer client and a Policy configuration, specifying the decision rule to evaluate.

```go
import (
    "github.com/aserto-dev/go-aserto"
    "github.com/aserto-dev/go-aserto/az"
    "github.com/aserto-dev/go-aserto/middleware"
    "github.com/aserto-dev/go-aserto/middleware/httpz"
)

// Create an authorizer client.
azClient, err := az.New(
    aserto.WithAddr("localhost:8282"),
    aserto.WithInsecure(true),
)

// Create HTTP middleware.
mw := httpz.New(
    azClient,
    middleware.Policy{
      Decision: "allowed",  // policy rule to evaluate.
    },
)
```

--------------------------------

### Interact with Authorizer gRPC Endpoint

Source: https://www.topaz.sh/docs/getting-started

This snippet demonstrates how to interact with the Topaz authorizer endpoint using gRPC. It requires the installation of 'grpcui' or 'grpcurl' and points them to localhost:8282.

```shell
grpcui --insecure localhost:8282
```

--------------------------------

### Initialize Aserto Client

Source: https://www.topaz.sh/docs/software-development-kits/javascript/spa

Demonstrates how to obtain an access token via Auth0 and instantiate the AsertoClient to manage display state.

```javascript
import createAuth0Client from '@auth0/aserto-spa-js';
const auth0 = await createAuth0Cient({
  domain: '<AUTH0_DOMAIN>',
  client_id: '<AUTH0_CLIENT_ID>',
  redirect_uri: '<MY_CALLBACK_URL>'
});
const accessToken = await auth0.getTokenSilently();

import createAsertoClient from '@aserto/aserto-spa-js';
const aserto = await createAsertoClient({
  accessToken: accessToken,
  serviceUrl: 'https://service-url',
  endpoint: '/__displaystatemap'
});

await aserto.reload();
```

--------------------------------

### POST /api/v2/authz/is

Source: https://www.topaz.sh/docs/getting-started

Evaluates an authorization request to determine if a specific identity is permitted to perform an action.

```APIDOC
## POST /api/v2/authz/is

### Description
Issue an authorization request to verify if a user is allowed to perform a specific action based on the policy context.

### Method
POST

### Endpoint
https://localhost:8383/api/v2/authz/is

### Request Body
- **identity_context** (object) - Required - The identity of the user requesting access
- **policy_context** (object) - Required - The path and expected decisions for the authorization check

### Request Example
{
  "identity_context": {
    "type": "IDENTITY_TYPE_SUB",
    "identity": "rick@the-citadel.com"
  },
  "policy_context": {
    "path": "todoApp.GET.todos",
    "decisions": ["allowed"]
  }
}

### Response
#### Success Response (200)
- **decision** (boolean) - Whether the action is allowed

#### Response Example
{
  "decision": true
}
```

--------------------------------

### Initialize Directory Client

Source: https://www.topaz.sh/docs/software-development-kits/javascript/express

Configures and initializes the DirectoryServiceV3 client. Demonstrates how to provide connection details and override specific service configurations like the writer client.

```typescript
import { DirectoryServiceV3 } from "@aserto/aserto-node";

const directoryClient = DirectoryServiceV3({
  url: 'localhost:9292',
  caFile: `${process.env.HOME}/.local/share/topaz/certs/grpc-ca.crt`
});

// Example with custom writer configuration
const customClient = DirectoryServiceV3({
  url: 'localhost:9292',
  writer: {
    url: 'localhost:9393'
  }
});
```

--------------------------------

### Trust Topaz Development Certificates

Source: https://www.topaz.sh/docs/getting-started

Adds Topaz's self-signed SSL certificates to the system's trust store. This is necessary for the Topaz console UI to load successfully in browsers.

```bash
topaz certs trust  

```

--------------------------------

### Create ASP.NET Core MVC Project

Source: https://www.topaz.sh/docs/software-development-kits/dotnet/dotnetcore

Commands to create a new ASP.NET Core MVC project directory and initialize a new MVC application using the .NET CLI. This sets up the basic structure for the web application.

```bash
md dotnetmvc
cd dotnetmvc

md src
cd src

dotnet new mvc -n QuickstartMVC
```

--------------------------------

### Remove Topaz Development Certificates

Source: https://www.topaz.sh/docs/getting-started

Removes Topaz's self-signed SSL certificates from the system's trust store. Use this command if you no longer need to trust the Topaz development certificates.

```bash
topaz certs trust --remove  

```

--------------------------------

### Authorize User Request via Topaz CLI

Source: https://www.topaz.sh/docs/getting-started

This snippet shows how to perform an authorization request using the Topaz CLI. It utilizes the 'authorizer eval' command with a JSON payload similar to the REST API, specifying identity and policy contexts.

```shell
topaz authorizer eval '{ 
     "identity_context": {
          "type": "IDENTITY_TYPE_SUB",
          "identity": "rick@the-citadel.com"
     },
     "policy_context": {
          "path": "todoApp.GET.todos",
          "decisions": ["allowed"]
     }
}' -i
```

--------------------------------

### Authorize User Request via REST API

Source: https://www.topaz.sh/docs/getting-started

This snippet demonstrates how to issue an authorization request to verify if a user is allowed to perform a specific action. It uses cURL to send a POST request to the /api/v2/authz/is endpoint with JSON payload specifying identity and policy contexts.

```shell
curl -k -X POST 'https://localhost:8383/api/v2/authz/is' \
-H 'Content-Type: application/json' \
-d '{
     "identity_context": {
          "type": "IDENTITY_TYPE_SUB",
          "identity": "rick@the-citadel.com"
     },
     "policy_context": {
          "path": "todoApp.GET.todos",
          "decisions": ["allowed"]
     }
}'
```

--------------------------------

### Install aserto-rails Gem

Source: https://www.topaz.sh/docs/software-development-kits/ruby/rails

Instructions for installing the aserto-rails gem into a Ruby on Rails application. This involves adding the gem to the Gemfile and running bundle install, or installing it directly via gem install.

```ruby
gem "aserto-rails"

bundle install
```

```ruby
gem install aserto-rails
```

--------------------------------

### Initialize Topaz configuration

Source: https://www.topaz.sh/docs/deployment/binary

Generates a new configuration file for Topaz using a specific policy template. This command creates the necessary YAML configuration in the user's home directory.

```bash
./topaz config new -d -r ghcr.io/aserto-policies/policy-todo:latest -n todo
```

--------------------------------

### LDAP Plugin Configuration Example

Source: https://www.topaz.sh/docs/command-line-interface/ds-load-cli/plugins/ldap

A sample YAML configuration file for the LDAP plugin. This demonstrates how to specify connection details, base DN, filters, and other settings for connecting to an LDAP directory.

```yaml
---
host: "directory.prod.aserto.com:8443"
api-key: "<your-directory-api-key>"
tenant-id: "<your-tenant-id>"
ldap:
  base-dn: "dc=aserto,dc=com"
  user: "CN=aserto,CN=Users,DC=aserto,DC=com"
  password: "<ldap-user-password>"
  host: "ldap://localhost:1389"
  user-filter: "(&(objectClass=organizationalPerson))"
  group-filter: "(&(objectClass=group))"
  id-field: "objectGUID"

```

--------------------------------

### Connect HTTP Middleware with net/http

Source: https://www.topaz.sh/docs/software-development-kits/go/middleware-http

Provides an example of connecting the configured HTTP middleware to a route handler using Go's built-in net/http package. The middleware is wrapped around the actual request handler.

```go
func Hello(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte(`"hello"`))
}

// Create a router.
mux := http.NewServeMux()

// Attach middleware to route handler.
mux.Handle("/hello", mw.HandlerFunc(Hello))
```

--------------------------------

### Download Topaz binary release via CLI

Source: https://www.topaz.sh/docs/deployment/binary

Uses curl and the GitHub API to fetch the latest Topaz release tarball for specific Linux architectures. It parses the release JSON to find the correct download URL and saves the output as topaz.zip.

```bash
TOPAZ_PLATFORM=topaz_linux_x86
TOPAZ_URL=$(curl -s https://api.github.com/repos/aserto-dev/topaz/releases/latest|grep browser_download_url|grep $TOPAZ_PLATFORM|cut -d\" -f4)
curl -L $TOPAZ_URL > topaz.zip
```

```bash
TOPAZ_PLATFORM=topaz_linux_arm64
TOPAZ_URL=$(curl -s https://api.github.com/repos/aserto-dev/topaz/releases/latest|grep browser_download_url|grep $TOPAZ_PLATFORM|cut -d\" -f4)
curl -L $TOPAZ_URL > topaz.zip
```

--------------------------------

### Import and Export Directory Data with Aserto

Source: https://www.topaz.sh/docs/software-development-kits/javascript/express

Demonstrates how to perform bulk imports of objects and relations into the Aserto directory using an async iterable, and how to export existing directory data.

```javascript
import { ImportMsgCase, ImportOpCode, objectPropertiesAsStruct } from "@aserto/aserto-node"
const importRequest = createAsyncIterable([
  {
    opCode: ImportOpCode.SET,
    msg: {
      case: ImportMsgCase.OBJECT,
      value: {
        id: "import-user",
        type: "user",
        properties: objectPropertiesAsStruct({ foo: "bar" }),
        displayName: "name1",
      },
    },
  },
  {
    opCode: ImportOpCode.SET,
    msg: {
      case: ImportMsgCase.RELATION,
      value: {
        subjectId: "import-user",
        subjectType: "user",
        objectId: "import-group",
        objectType: "group",
        relation: "member",
      },
    },
  },
]);
const resp = await directoryClient.import(importRequest);
await (readAsyncIterable(resp));

const response = await readAsyncIterable(
  await directoryClient.export({ options: "all" })
);
```

--------------------------------

### Install Python Authorizer Client

Source: https://www.topaz.sh/docs/software-development-kits/python/api-client

Installs the Topaz Authorizer Python client library using either pip or Poetry. This package is essential for integrating authorization logic into Python applications.

```bash
pip install -U aserto
```

```bash
poetry add aserto
```

--------------------------------

### Delete Object Example - Topaz CLI

Source: https://www.topaz.sh/docs/command-line-interface/topaz-cli/directory

An example of deleting a user object and its associated relations using the Topaz directory CLI. The `with_relations` flag is set to true to remove all related data.

```bash
topaz directory delete object '  
{
  "object_type": "user",
  "object_id": "newuser@the-citadel.com",
  "with_relations": true
}' --insecure
```

```json
{
  "result": {}
}
```

--------------------------------

### Set Relation Example - Topaz CLI

Source: https://www.topaz.sh/docs/command-line-interface/topaz-cli/directory

An example of setting a 'member' relation between a 'group' and a 'user' using the Topaz directory CLI. It demonstrates providing the relation details within a JSON payload.

```bash
topaz directory set relation '  
{
  "relation": {
    "object_type": "group",
    "object_id": "admin",
    "relation": "member",
    "subject_type": "user",
    "subject_id": "newuser@the-citadel.com"
  }
}' --insecure
```

```json
{
  "result": {
    "object_type": "group",
    "object_id": "admin",
    "relation": "member",
    "subject_type": "user",
    "subject_id": "newuser@the-citadel.com",
    "subject_relation": "",
    "created_at": "2024-05-21T23:58:30.747420386Z",
    "updated_at": "2024-05-21T23:58:30.747420386Z",
    "etag": "3727662736522093748"
  }
}
```

--------------------------------

### Configure Policy Path for HTTP Middleware

Source: https://www.topaz.sh/docs/software-development-kits/go/middleware-http

Illustrates methods for configuring how the policy path is determined. This includes adding a prefix to the inferred path from the URL or providing a custom mapping function.

```go
mw.WithPolicyFromURL("peoplefinder")
```

```go
mw.WithPolicyPathMapper(
    func(r *http.Request) string {
        // custom logic inspects the request and returns the policy path.
    },
)
```

--------------------------------

### Kubernetes Deployment Commands

Source: https://www.topaz.sh/docs/deployment/sidecar

Commands to apply Kubernetes configurations, retrieve the pod name dynamically, and port-forward the application for local testing.

```bash
# Apply deployment
kubectl apply -f . --recursive

# Get pod name
TODO_POD_NAME=$(kubectl get pods -n default -l 'app=todo' -o jsonpath="{.items[0].metadata.name}")

# Port forward
kubectl --namespace default port-forward $TODO_POD_NAME 3001:3001
```

--------------------------------

### Connect HTTP Middleware with gorilla/mux

Source: https://www.topaz.sh/docs/software-development-kits/go/middleware-http

Shows how to apply authorization middleware to all routes within a router using the gorilla/mux package. The middleware is added using the router's `Use` method.

```go
func Hello(w http.ResponseWriter, r *http.Request) {
	name = mux.Vars(r)["name"]
    w.Write([]byte(fmt.Sprintf(`"hello %s"`, name)))
}

r := mux.NewRouter()  // Create new gorilla/mux Router.
r.Use(mw)             // Attach authorization middleware to all routes.

r.HandleFunc("/hello/{name}", Hello) // Define route.
```

--------------------------------

### Clone Todo Application Repository

Source: https://www.topaz.sh/docs/getting-started/samples/test-application

Clones the 'todo-application' repository from GitHub. This is the first step to building and running the application from source.

```bash
git clone https://github.com/aserto-demo/todo-application.git  
```

--------------------------------

### Example Rego Policy for Department Deletion

Source: https://www.topaz.sh/docs/policies

A comprehensive Rego policy example for deleting a department. It combines an ABAC rule (user in 'IT' department) and a permission check (user has 'can-delete' permission) using 'ds.check'.

```rego
package sample.DELETE.api.departments  
  
default allowed = false  
  
## allow if the department property of the user is "IT"  
allowed {
  input.user.properties.department == "IT"
}
  
## allow if the user has the "can-delete" permission on the department identified by "id"  
allowed {
  ds.check({
    "object_type": "department",
    "object_id": input.resource.id,
    "relation": "can-delete",
    "subject_type": "user",
    "subject_id": input.user.id
  })
}

```

--------------------------------

### Example of Removing an Image with policy rm

Source: https://www.topaz.sh/docs/command-line-interface/policy-cli/rm

This example demonstrates the practical application of the 'policy rm' command to remove a specific image tag. It shows the command execution and the confirmation output, including the removed reference.

```bash
$ policy rm ghcr.io/ogazitt/peoplefinder:1.0.0

Removed reference.
reference: ghcr.io/ogazitt/peoplefinder:1.0.0
```

--------------------------------

### Initialize Aserto Client with init()

Source: https://www.topaz.sh/docs/software-development-kits/javascript/react

Initializes the Aserto client with various options including service URL, endpoint name, access token, error handling, and default display state. It also logs the resulting display state map.

```javascript
const { init, displayStateMap } = useAserto()  
await init({  
  serviceUrl: 'http://service-url', // defaults to windows.location.origin  
  endpointName: '/__displaystatemap', // defaults to '/__displaystatemap'  
  accessToken: '<VALID ACCESS TOKEN>', // REQUIRED  
  throwOnError: true, // true: re-throw errors. false: set error object. defaults to true.  
  defaultDisplayState: {  
    // an optional default display state (default values below)  
    visible: false,  
    enabled: false,  
  },  
})  
  
// log the display state map to the console  
console.log(displayStateMap)  

```

--------------------------------

### Define Resource Mapper Type and Examples (TypeScript)

Source: https://www.topaz.sh/docs/software-development-kits/javascript/express

Defines the `ResourceMapper` type in TypeScript, which can be either a direct `ResourceContext` object or an asynchronous function that returns one. Provides examples of both a function-based mapper using request parameters and a static context.

```typescript
// provides a custom resource context,
type ResourceMapper =
  | ResourceContext
  | ((req?: Request) => Promise<ResourceContext>);

// examples
async (req: Request) => { return { customKey: req.params.id } };
// or just a plain resource context
{ customKey: "customValue" }
```