Topaz Directory Checks API

openapi: 3.0.3
info:
  title: Topaz and Directory Authorizer Directory Checks API
  description: 'Topaz is an open-source (Apache-2.0) authorizer for fine-grained, policy-based, real-time access control, maintained by Aserto (github.com/aserto-dev/topaz). It combines the Open Policy Agent (OPA) decision engine with a built-in Zanzibar-style relationship directory. Topaz is SELF-HOSTED: you run the authorizer yourself (Docker image ghcr.io/aserto-dev/topaz or a binary), and it exposes gRPC plus REST (gRPC-gateway) APIs from your own instance. The base URL is therefore your own deployment - by default the REST gateway listens on https://localhost:8383 (authorizer gRPC on :8282, directory gRPC on :9292, local web Console on :8080). In split deployments the directory REST endpoints may be exposed on :9393. This document models the REST surface: the Authorizer API (is / decisiontree / query and policy listing) under /api/v2, and the Directory v3 API (objects, relations, and checks) under /api/v3/directory. Aserto is the commercial hosted control plane built on Topaz; on Aserto the same contracts are served from tenant-scoped hosts such as https://authorizer.prod.aserto.com and https://directory.prod.aserto.com.'
  version: '1.0'
  contact:
    name: Topaz
    url: https://www.topaz.sh
  license:
    name: Apache-2.0
    url: https://github.com/aserto-dev/topaz/blob/main/LICENSE
servers:
- url: https://localhost:8383
  description: Self-hosted Topaz REST gateway (default). Replace with your own instance host.
- url: https://authorizer.prod.aserto.com
  description: Aserto hosted control plane (Authorizer API), tenant-scoped.
- url: https://directory.prod.aserto.com
  description: Aserto hosted control plane (Directory API), tenant-scoped.
security:
- apiKey: []
tags:
- name: Directory Checks
  description: Graph-based check and graph-expansion queries over the directory.
paths:
  /api/v3/directory/check:
    post:
      operationId: check
      tags:
      - Directory Checks
      summary: Check
      description: Returns whether a subject has a given relation or permission on an object by traversing the directory relationship graph. The data-driven, Zanzibar-style access check.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckRequest'
      responses:
        '200':
          description: The check result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v3/directory/graph:
    get:
      operationId: getGraph
      tags:
      - Directory Checks
      summary: Get graph
      description: Expands the object graph from an anchor to return the set of subjects or objects reachable through a relation (for example, all users who are members of a group, directly or transitively).
      parameters:
      - name: object_type
        in: query
        schema:
          type: string
      - name: object_id
        in: query
        schema:
          type: string
      - name: relation
        in: query
        schema:
          type: string
      - name: subject_type
        in: query
        schema:
          type: string
      - name: subject_id
        in: query
        schema:
          type: string
      responses:
        '200':
          description: The expanded graph result.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CheckRequest:
      type: object
      properties:
        object_type:
          type: string
        object_id:
          type: string
        relation:
          type: string
        subject_type:
          type: string
        subject_id:
          type: string
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
    CheckResponse:
      type: object
      properties:
        check:
          type: boolean
  responses:
    Unauthorized:
      description: Authentication failed or the API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Self-hosted Topaz may run with no authentication (default), with a static API key, or behind mTLS. When keys are configured (and on the Aserto hosted service) pass the key in the Authorization header, along with the Aserto-Tenant-Id header on Aserto.