openapi: 3.0.3
info:
  title: Topaz and Directory Authorizer Directory Objects 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 Objects
  description: Objects in the Zanzibar-style directory - users, groups, resources, and other entities.
paths:
  /api/v3/directory/object/{object_type}/{object_id}:
    parameters:
    - $ref: '#/components/parameters/ObjectType'
    - $ref: '#/components/parameters/ObjectId'
    get:
      operationId: getObject
      tags:
      - Directory Objects
      summary: Get object
      description: Retrieves a single directory object by its type and id.
      responses:
        '200':
          description: The requested object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteObject
      tags:
      - Directory Objects
      summary: Delete object
      description: Deletes a directory object by its type and id.
      responses:
        '200':
          description: Deletion result.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v3/directory/objects/{object_type}:
    get:
      operationId: getObjects
      tags:
      - Directory Objects
      summary: List objects of a type
      description: Lists directory objects of a given type, with pagination.
      parameters:
      - $ref: '#/components/parameters/ObjectType'
      - name: page.size
        in: query
        required: false
        schema:
          type: integer
      - name: page.token
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A page of objects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Object'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v3/directory/object:
    post:
      operationId: setObject
      tags:
      - Directory Objects
      summary: Set object
      description: Creates or updates a directory object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                object:
                  $ref: '#/components/schemas/Object'
      responses:
        '200':
          description: The created or updated object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Object'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Authentication failed or the API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    ObjectId:
      name: object_id
      in: path
      required: true
      description: The object identifier.
      schema:
        type: string
    ObjectType:
      name: object_type
      in: path
      required: true
      description: The object type, for example user, group, or resource.
      schema:
        type: string
  schemas:
    Object:
      type: object
      properties:
        type:
          type: string
          example: user
        id:
          type: string
          example: euang@acmecorp.com
        display_name:
          type: string
        properties:
          type: object
          additionalProperties: true
    Error:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string
  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.