{
  "openapi": "3.1.0",
  "info": {
    "title": "Gathrr event integration credentials",
    "version": "1.2.0",
    "description": "Event-bound server integration keys. Registration references exclude personal fields. Admission keys require explicit zone grants. Expiry/revocation and a 6000-request/minute key quota are enforced. Development/staging sandbox only."
  },
  "servers": [
    {
      "url": "/api/v1"
    }
  ],
  "paths": {
    "/organizations/{organization_id}/events/{event_id}/api-keys": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationId"
        },
        {
          "$ref": "#/components/parameters/EventId"
        }
      ],
      "post": {
        "operationId": "createEventIntegrationKey",
        "security": [
          {
            "BrowserSession": [],
            "CsrfToken": []
          }
        ],
        "description": "Requires integration.manage. Returns the key secret once; store it in a server-side secret manager.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateKeyInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Key created; api_key is shown once",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatedKey"
                }
              }
            }
          },
          "403": {
            "description": "The caller lacks event-scoped integration.manage permission"
          },
          "422": {
            "description": "Invalid key name, scope or expiry"
          }
        }
      },
      "get": {
        "operationId": "listEventIntegrationKeys",
        "security": [
          {
            "BrowserSession": []
          }
        ],
        "responses": {
          "200": {
            "description": "Safe key metadata, zone grants and last-day request usage; secrets and digests are excluded"
          }
        }
      }
    },
    "/organizations/{organization_id}/events/{event_id}/api-keys/{key_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/OrganizationId"
        },
        {
          "$ref": "#/components/parameters/EventId"
        },
        {
          "$ref": "#/components/parameters/KeyId"
        }
      ],
      "delete": {
        "operationId": "revokeEventIntegrationKey",
        "security": [
          {
            "BrowserSession": [],
            "CsrfToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Credential revoked; retry returns the same revoked state"
          },
          "403": {
            "description": "The caller lacks event-scoped integration.manage permission"
          },
          "404": {
            "description": "Credential not found"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BrowserSession": {
        "type": "apiKey",
        "in": "cookie",
        "name": "gathrr_access"
      },
      "CsrfToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-CSRF-Token"
      }
    },
    "parameters": {
      "OrganizationId": {
        "name": "organization_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "EventId": {
        "name": "event_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "KeyId": {
        "name": "key_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "schemas": {
      "CreateKeyInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "scopes",
          "expires_at"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 2,
            "maxLength": 80
          },
          "scopes": {
            "type": "array",
            "minItems": 1,
            "maxItems": 5,
            "items": {
              "enum": [
                "registration.write",
                "registration.read",
                "credential.revoke",
                "attendance.read",
                "admission.write"
              ]
            }
          },
          "expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Expiry must be from one hour to one year in the future."
          },
          "allowed_zones": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "type": "string",
              "pattern": "^[a-z0-9-]{1,60}$"
            },
            "default": []
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "scopes": {
                  "contains": {
                    "const": "admission.write"
                  }
                }
              }
            },
            "then": {
              "required": [
                "allowed_zones"
              ],
              "properties": {
                "allowed_zones": {
                  "minItems": 1
                }
              }
            }
          }
        ]
      },
      "CreatedKey": {
        "type": "object",
        "required": [
          "data"
        ],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "id",
              "name",
              "scopes",
              "expires_at",
              "api_key"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "scopes": {
                "type": "array",
                "items": {
                  "enum": [
                    "registration.write",
                    "registration.read",
                    "credential.revoke",
                    "attendance.read",
                    "admission.write"
                  ]
                },
                "maxItems": 5
              },
              "expires_at": {
                "type": "string",
                "format": "date-time"
              },
              "api_key": {
                "type": "string",
                "pattern": "^gk_live_[0-9a-f-]{36}\\.[A-Za-z0-9_-]{43}$",
                "writeOnly": true
              },
              "allowed_zones": {
                "type": "array",
                "maxItems": 100,
                "items": {
                  "type": "string",
                  "pattern": "^[a-z0-9-]{1,60}$"
                },
                "default": []
              }
            }
          }
        }
      }
    }
  }
}