4chems Authz API

openapi: 3.2.0
info:
  title: platform-api Authz API
  description: 'Platform API: infrastructure, operational, and customer tiers.'
  version: 0.12.1
tags:
- name: authz
paths:
  /v1/me/access:
    get:
      tags:
      - authz
      summary: Get My Access
      description: 'Return the caller''s access level per related tenant. Call this to check

        what the current caller is authorized to do before attempting an action

        that requires a specific level, or to discover a pending invitation or

        access request.


        One entry per tenant the subject relates to via an active assignment, a

        pending invitation to their verified email, or a pending access request

        (ADR 0016 decision 6); a subject with no relation gets an empty list.

        `subscription` is the tenant''s `{state, expires_at, grace_ends_at}` (UC-096);

        a standard tenant reports `active` with null dates.'
      operationId: get_my_access
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/TenantAccessOut'
                type: array
                title: Response Get My Access
      security:
      - HTTPBearer: []
  /v1/tenant/members:
    get:
      tags:
      - authz
      summary: List Members
      description: 'List tenant members with their effective role x scope assignments.


        Members are subjects with at least one active assignment at the caller''s

        tenant scope. Only their assignments at that same tenant scope are

        included — a subject''s assignments on another tenant are never disclosed

        to a viewer of this one (no cross-tenant existence leak).'
      operationId: list_members
      security:
      - HTTPBearer: []
      parameters:
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Tenant Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembersListOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/tenant/members/{sub}/assignments:
    post:
      tags:
      - authz
      summary: Grant Assignment
      description: 'Grant a role x scope assignment to a tenant member.


        Enforces the grantability policy (app/authz/grants.py): no privilege

        escalation, no cross-tenant grants, member-only. An `admin` may grant up

        to `admin`; only an `owner` may grant `owner` (ADR 0016 decision 3).

        Every grant is recorded in the tamper-evident audit trail (UC-039) with

        the token''s `azp`/`act`/`tier` (ADR 0016 decision 5).'
      operationId: grant_assignment
      security:
      - HTTPBearer: []
      parameters:
      - name: sub
        in: path
        required: true
        schema:
          type: string
          title: Sub
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Tenant Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignmentIn'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssignmentOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-destructive: false
      x-idempotent: false
  /v1/tenant/members/{sub}/assignments/{id}:
    delete:
      tags:
      - authz
      summary: Revoke Assignment
      description: 'Revoke a role x scope assignment from a tenant member.


        Tenant-scoped (ADR 0016 code fix): an assignment id belonging to a

        different tenant answers `404 assignment.not_found`, indistinguishable

        from an unknown id — no cross-tenant existence leak. An `admin` may

        revoke up to `admin`; only an `owner` may revoke an `owner` assignment.

        The last `owner` of a tenant cannot be revoked (self-lockout guard,

        re-pointed from the old "last tenant admin" rule). Every revocation is

        recorded in the tamper-evident audit trail (UC-039) with the token''s

        `azp`/`act`/`tier`.'
      operationId: revoke_assignment
      security:
      - HTTPBearer: []
      parameters:
      - name: sub
        in: path
        required: true
        schema:
          type: string
          title: Sub
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Id
      - name: tenant_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Tenant Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-destructive: true
      x-idempotent: true
components:
  schemas:
    Level:
      type: string
      enum:
      - none
      - requester
      - viewer
      - member
      - admin
      - owner
      title: Level
    TenantAccessOut:
      properties:
        tenant:
          type: string
          title: Tenant
        level:
          $ref: '#/components/schemas/Level'
        via:
          type: string
          title: Via
        subscription:
          $ref: '#/components/schemas/SubscriptionOut'
      type: object
      required:
      - tenant
      - level
      - via
      - subscription
      title: TenantAccessOut
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    SubscriptionState:
      type: string
      enum:
      - trialing
      - expired
      - erased
      - active
      title: SubscriptionState
      description: Commercial state (UC-096, UC-086 D7); `TrialStatus` is provisioning only.
    MemberOut:
      properties:
        subject:
          type: string
          title: Subject
        assignments:
          items:
            $ref: '#/components/schemas/AssignmentOut'
          type: array
          title: Assignments
      type: object
      required:
      - subject
      - assignments
      title: MemberOut
    SubscriptionOut:
      properties:
        state:
          $ref: '#/components/schemas/SubscriptionState'
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        grace_ends_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Grace Ends At
      type: object
      required:
      - state
      - expires_at
      - grace_ends_at
      title: SubscriptionOut
    MembersListOut:
      properties:
        tenant_id:
          type: string
          title: Tenant Id
        members:
          items:
            $ref: '#/components/schemas/MemberOut'
          type: array
          title: Members
      type: object
      required:
      - tenant_id
      - members
      title: MembersListOut
    AssignmentIn:
      properties:
        role:
          type: string
          title: Role
        scope_type:
          type: string
          title: Scope Type
        scope_id:
          type: string
          title: Scope Id
      type: object
      required:
      - role
      - scope_type
      - scope_id
      title: AssignmentIn
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AssignmentOut:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        subject_type:
          type: string
          title: Subject Type
        subject:
          type: string
          title: Subject
        role:
          type: string
          title: Role
        scope_type:
          type: string
          title: Scope Type
        scope_id:
          type: string
          title: Scope Id
        expires_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Expires At
        granted_by:
          type: string
          title: Granted By
        granted_at:
          type: string
          format: date-time
          title: Granted At
      type: object
      required:
      - id
      - subject_type
      - subject
      - role
      - scope_type
      - scope_id
      - expires_at
      - granted_by
      - granted_at
      title: AssignmentOut
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer