openapi: 3.0.3
info:
  title: Topaz and Directory Authorizer Directory Relations 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 Relations
  description: Relations (tuples) connecting subjects to objects in the directory graph.
paths:
  /api/v3/directory/relation:
    get:
      operationId: getRelation
      tags:
      - Directory Relations
      summary: Get relation
      description: Retrieves a single relation (tuple) identified by its object, relation name, and subject.
      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 requested relation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Relation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: setRelation
      tags:
      - Directory Relations
      summary: Set relation
      description: Creates or updates a relation between a subject and an object.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                relation:
                  $ref: '#/components/schemas/Relation'
      responses:
        '200':
          description: The created or updated relation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Relation'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteRelation
      tags:
      - Directory Relations
      summary: Delete relation
      description: Deletes a relation identified by its object, relation name, and subject.
      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: Deletion result.
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v3/directory/relations:
    get:
      operationId: getRelations
      tags:
      - Directory Relations
      summary: List relations
      description: Lists relations matching an optional object and/or subject filter, with pagination.
      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
      - name: page.size
        in: query
        schema:
          type: integer
      - name: page.token
        in: query
        schema:
          type: string
      responses:
        '200':
          description: A page of relations.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Relation'
        '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'
  schemas:
    Relation:
      type: object
      properties:
        object_type:
          type: string
          example: group
        object_id:
          type: string
          example: admin
        relation:
          type: string
          example: member
        subject_type:
          type: string
          example: user
        subject_id:
          type: string
          example: euang@acmecorp.com
    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.