{
  "openapi": "3.1.0",
  "info": {
    "title": "Identity & Access Directory Service",
    "summary": "Zero-trust identity provisioning, RBAC roles, and session introspection in JSON format",
    "description": "Manages organization members, fine-grained role assignments, and short-lived session tokens.",
    "version": "3.0.1",
    "license": {
      "name": "MPL-2.0",
      "identifier": "MPL-2.0"
    }
  },
  "servers": [
    {
      "url": "/api/mock/identity-directory-service",
      "description": "Built-in OpenAPI 3.1 Mock Server"
    },
    {
      "url": "https://httpbin.org/anything",
      "description": "HTTPBin Live Echo Runner"
    }
  ],
  "tags": [
    {
      "name": "Users",
      "description": "Directory member lifecycle"
    },
    {
      "name": "Roles",
      "description": "Role-based access control policies"
    }
  ],
  "paths": {
    "/v1/users": {
      "get": {
        "operationId": "listUsers",
        "summary": "List directory users",
        "tags": ["Users"],
        "parameters": [
          {
            "name": "department",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "examples": ["Platform Engineering"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Directory user list",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "users": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/UserRecord"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "inviteUser",
        "summary": "Invite user to organization",
        "tags": ["Users"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InviteUserPayload"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "User invitation created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserRecord"
                }
              }
            }
          }
        }
      }
    },
    "/v1/users/{userId}/roles": {
      "put": {
        "operationId": "assignUserRoles",
        "summary": "Replace RBAC roles for a user",
        "tags": ["Roles"],
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "examples": ["usr_77210a"]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["roles"],
                "properties": {
                  "roles": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "examples": [["admin", "spec-editor"]]
                  },
                  "expiresAt": {
                    "type": ["string", "null"],
                    "format": "date-time",
                    "examples": ["2027-01-01T00:00:00Z"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated role bindings",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserRecord"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UserRecord": {
        "type": "object",
        "required": ["id", "email", "roles", "mfaEnabled"],
        "properties": {
          "id": {
            "type": "string",
            "examples": ["usr_77210a"]
          },
          "email": {
            "type": "string",
            "format": "email",
            "examples": ["ada@example.com"]
          },
          "displayName": {
            "type": ["string", "null"],
            "examples": ["Ada Lovelace"]
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [["platform-admin", "billing-viewer"]]
          },
          "mfaEnabled": {
            "type": "boolean",
            "examples": [true]
          }
        }
      },
      "InviteUserPayload": {
        "type": "object",
        "required": ["email", "roles"],
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "examples": ["grace@example.com"]
          },
          "displayName": {
            "type": ["string", "null"],
            "examples": ["Grace Hopper"]
          },
          "roles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "examples": [["developer"]]
          }
        }
      }
    }
  }
}