{
  "openapi": "3.1.0",
  "info": {
    "title": "ArcticSign Enterprise API",
    "version": "1.0.0",
    "description": "REST API for iOS developer certificate issuance. Register UDIDs, retrieve certificates, and manage your account.",
    "contact": { "email": "support@arcticsign.app" }
  },
  "servers": [
    { "url": "https://enterprise.arcticsign.app", "description": "Production" },
    { "url": "http://localhost:5173", "description": "Local development" }
  ],
  "security": [{ "ApiKeyAuth": [] }],
  "paths": {
    "/v1/devices": {
      "post": {
        "operationId": "registerDevice",
        "summary": "Register a device",
        "description": "Register a UDID and retrieve its certificate. Response includes signed download URLs for .mobileprovision and .p12 files. Requires an idempotency key to prevent duplicate upstream charges.",
        "tags": ["Devices"],
        "parameters": [
          { "$ref": "#/components/parameters/IdempotencyKey" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/RegisterDeviceRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Device registered successfully",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponse" } } }
          },
          "402": { "$ref": "#/components/responses/InsufficientFunds" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "502": { "$ref": "#/components/responses/UpstreamError" },
          "504": { "$ref": "#/components/responses/TimeoutStuck" }
        }
      },
      "get": {
        "operationId": "listDevices",
        "summary": "List devices",
        "description": "Returns a paginated list of registered devices with optional filters.",
        "tags": ["Devices"],
        "parameters": [
          { "name": "plan", "in": "query", "schema": { "type": "string", "enum": ["super0", "developer_plan"] } },
          { "name": "external_id", "in": "query", "schema": { "type": "string" }, "description": "Filter by your external user ID" },
          { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Pagination cursor from previous response" },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "maximum": 100 } }
        ],
        "responses": {
          "200": {
            "description": "Paginated device list",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceListResponse" } } }
          }
        }
      }
    },
    "/v1/devices/{id}": {
      "get": {
        "operationId": "getDevice",
        "summary": "Get a device",
        "tags": ["Devices"],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Device details with certificates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceResponse" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/certificates/{id}": {
      "get": {
        "operationId": "getCertificate",
        "summary": "Get certificate with fresh download URLs",
        "tags": ["Certificates"],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Certificate with signed URLs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CertificateResponse" } } } },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/v1/certificates/{id}/mobileprovision": {
      "get": {
        "operationId": "downloadMobileprovision",
        "summary": "Download .mobileprovision file",
        "tags": ["Certificates"],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Signed download token from certificate response" }
        ],
        "responses": {
          "200": { "description": "Binary .mobileprovision file", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }
        }
      }
    },
    "/v1/certificates/{id}/p12": {
      "get": {
        "operationId": "downloadP12",
        "summary": "Download .p12 file",
        "tags": ["Certificates"],
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Signed download token from certificate response" }
        ],
        "responses": {
          "200": { "description": "Binary .p12 file", "content": { "application/x-pkcs12": { "schema": { "type": "string", "format": "binary" } } } }
        }
      }
    },
    "/v1/account": {
      "get": {
        "operationId": "getAccount",
        "summary": "Get account info",
        "tags": ["Account"],
        "responses": {
          "200": { "description": "Account balance, pricing, and rate limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key with prefix `ask_live_` (production) or `ask_test_` (sandbox). Generate keys in your dashboard."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": { "type": "string" },
        "description": "Unique key to safely retry requests without duplicate charges"
      }
    },
    "schemas": {
      "RegisterDeviceRequest": {
        "type": "object",
        "required": ["udid", "plan"],
        "properties": {
          "udid": { "type": "string", "description": "Device UDID (format: XXXXXXXXX-XXXXXXXXXXXXXXXX)", "example": "00008110-001A2B3C4D5E6F7G" },
          "plan": { "type": "string", "enum": ["super0", "developer_plan"], "description": "Certificate plan" },
          "external_id": { "type": "string", "description": "Your internal user/customer ID for correlation" },
          "external_ref": { "type": "string", "description": "Your internal order or session reference" },
          "tags": { "type": "object", "description": "Arbitrary key-value metadata" }
        }
      },
      "DeviceResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "udid": { "type": "string" },
          "plan": { "type": "string" },
          "status": { "type": "string", "enum": ["ready", "stuck"] },
          "holder_name": { "type": "string" },
          "external_id": { "type": "string" },
          "external_ref": { "type": "string" },
          "tags": { "type": "object" },
          "expires_at": { "type": "string", "format": "date-time" },
          "issued_at": { "type": "string", "format": "date-time" },
          "certificate": { "$ref": "#/components/schemas/CertificateUrls" },
          "developer_certificate": { "$ref": "#/components/schemas/CertificateUrls" },
          "request_id": { "type": "string" }
        }
      },
      "CertificateUrls": {
        "type": "object",
        "properties": {
          "mobileprovision_url": { "type": "string", "format": "uri" },
          "p12_url": { "type": "string", "format": "uri" },
          "p12_password": { "type": "string" }
        }
      },
      "CertificateResponse": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "kind": { "type": "string", "enum": ["distribution", "development"] },
          "holder_name": { "type": "string" },
          "device_model": { "type": "string" },
          "mobileprovision_url": { "type": "string" },
          "p12_url": { "type": "string" },
          "p12_password": { "type": "string" },
          "expires_at": { "type": "string", "format": "date-time" }
        }
      },
      "DeviceListResponse": {
        "type": "object",
        "properties": {
          "data": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceListItem" } },
          "next_cursor": { "type": "string", "nullable": true }
        }
      },
      "DeviceListItem": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "udid": { "type": "string" },
          "plan": { "type": "string" },
          "holder_name": { "type": "string" },
          "external_id": { "type": "string" },
          "external_ref": { "type": "string" },
          "tags": { "type": "object" },
          "sandbox": { "type": "boolean" },
          "expires_at": { "type": "string", "format": "date-time" },
          "created_at": { "type": "string", "format": "date-time" }
        }
      },
      "AccountResponse": {
        "type": "object",
        "properties": {
          "balance_cents": { "type": "integer" },
          "pricing": {
            "type": "object",
            "properties": {
              "super0": { "type": "object", "properties": { "retail_cents": { "type": "integer" } } },
              "developer_plan": { "type": "object", "properties": { "retail_cents": { "type": "integer" } } }
            }
          },
          "rate_limit": {
            "type": "object",
            "properties": {
              "limit": { "type": "integer" },
              "remaining": { "type": "integer" },
              "reset": { "type": "integer" }
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "message": { "type": "string" }
            }
          }
        }
      }
    },
    "responses": {
      "InsufficientFunds": { "description": "Credit balance too low", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
      "RateLimited": { "description": "Too many requests", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
      "UpstreamError": { "description": "Upstream provider error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
      "TimeoutStuck": { "description": "Certificate polling timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } },
      "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }
    }
  }
}