openapi: 3.0.3
info:
  title: کلید API نوبیتکس
  version: "1.0.0"
  description: APIهای ایجاد، مشاهده، ویرایش و حذف کلید API نوبیتکس.

servers:
  - url: https://apiv2.nobitex.ir
  - url: https://testnetapiv2.nobitex.ir

tags:
  - name: کلید API
    description: ایجاد، مشاهده، حذف و ویرایش کلیدهای API

paths:
  /apikeys/create:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      operationId: createApiKey
      tags:
        - کلید API
      summary: ایجاد API Key
      description: |
        یک API Key جدید برای کاربر ایجاد می‌کند.

        ### نکات امنیتی
        - ارسال کد دوعاملی در هدر `X-TOTP` الزامی است.
        - `privateKey` فقط همین یک بار در پاسخ ساخت کلید نمایش داده می‌شود؛ آن را در محل امن ذخیره کنید.
        - بعد از ایجاد کلید، اعلان‌های امنیتی برای کاربر ارسال و رویداد در لاگ امنیتی ثبت می‌شود.
        - هر کاربر حداکثر ۲۰ کلید فعال می‌تواند داشته باشد.
        - `ipAddressesWhitelist` حداکثر ۱۵ مقدار IPv4/IPv6 می‌پذیرد.
        - `permissions` بعد از ساخت کلید قابل تغییر نیست.

        <div class="alert alert--warning">
        **محدودیت فراخوانی:** ۱۰ درخواست در دقیقه
        </div>
        <br/>
      security:
        - TokenAuth: []
      parameters:
        - $ref: "#/components/parameters/XTOTP"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/APIKeyCreateRequest"
            example:
              name: my-api-key
              description: API key for internal services
              permissions: READ,TRADE
              ipAddressesWhitelist:
                - 192.168.1.10
                - 10.0.0.5
              expirationDate: "2026-12-31T23:59:59Z"
      responses:
        "200":
          description: کلید با موفقیت ساخته شد
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyCreateResponse"
              example:
                status: ok
                privateKey: S5y19KewZzheCWCO4xqMcwwvtR8vQ-hHjE_cdjz-XxE=
                key:
                  createdAt: "2026-09-02T16:50:29.381869Z"
                  updatedAt: "2026-09-02T16:50:29.381876Z"
                  expirationDate: "2026-12-31T23:59:59Z"
                  description: API key for internal services
                  ipAddressesWhitelist:
                    - 192.168.1.10
                    - 10.0.0.5
                  key: 5XOCQZSPLQM4MiLzuUnZoBuqgYgTKl40W2X5j1pxfIA=
                  name: my-api-key
                  permissions: READ,TRADE
        "400":
          description: خطای اعتبارسنجی، کد دوعاملی یا محدودیت تعداد کلید/IP
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyFailedResponse"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

  /apikeys/list:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    get:
      operationId: listApiKeys
      tags:
        - کلید API
      summary: لیست API Keyها
      description: |
        لیست کلیدهای API متعلق به کاربر را برمی‌گرداند.

        <div class="alert alert--warning">
        **محدودیت فراخوانی:** ۱۰ درخواست در دقیقه
        </div>
        <br/>
      security:
        - TokenAuth: []
      responses:
        "200":
          description: لیست کلیدها
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyListResponse"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

  /apikeys/delete/{publicKey}:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      operationId: deleteApiKey
      tags:
        - کلید API
      summary: حذف API Key
      description: |
        یک API Key متعلق به کاربر را حذف می‌کند.

        ### نکات امنیتی
        - ارسال کد دوعاملی در هدر `X-TOTP` الزامی است.
        - بعد از حذف کلید، اعلان‌های امنیتی برای کاربر ارسال و رویداد در لاگ امنیتی ثبت می‌شود.

        <div class="alert alert--warning">
        **محدودیت فراخوانی:** ۱۰ درخواست در دقیقه
        </div>
        <br/>
      security:
        - TokenAuth: []
      parameters:
        - $ref: "#/components/parameters/PublicKey"
        - $ref: "#/components/parameters/XTOTP"
      responses:
        "200":
          description: حذف موفق
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusOnlyResponse"
              example:
                status: ok
        "400":
          description: کد دوعاملی ارسال نشده، نامعتبر یا برای کاربر فعال نیست
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyFailedResponse"
        "404":
          description: کلید پیدا نشد
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyFailedResponse"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

  /apikeys/update/{publicKey}:
    parameters:
      - $ref: "#/components/parameters/TraderBotUserAgent"
    post:
      operationId: updateApiKey
      tags:
        - کلید API
      summary: ویرایش API Key
      description: |
        مشخصات قابل تغییر یک API Key را ویرایش می‌کند.

        فقط `name`، `description` و `ipAddressesWhitelist` قابل تغییر هستند. دسترسی‌ها و تاریخ انقضا بعد از ساخت کلید تغییر نمی‌کنند.

        ### نکات امنیتی
        - ارسال کد دوعاملی در هدر `X-TOTP` الزامی است.
        - تغییر فهرست IPهای مجاز با اعلان امنیتی و ثبت رویداد در لاگ همراه است.

        <div class="alert alert--warning">
        **محدودیت فراخوانی:** ۱۰ درخواست در دقیقه
        </div>
        <br/>
      security:
        - TokenAuth: []
      parameters:
        - $ref: "#/components/parameters/PublicKey"
        - $ref: "#/components/parameters/XTOTP"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/APIKeyUpdateRequest"
            example:
              name: my-api-key
              description: API key for internal services
              ipAddressesWhitelist:
                - 192.168.1.10
                - 10.0.0.5
      responses:
        "200":
          description: ویرایش موفق
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyUpdateResponse"
        "400":
          description: خطای اعتبارسنجی یا کد دوعاملی
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyFailedResponse"
        "404":
          description: کلید پیدا نشد
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyFailedResponse"
        "429":
          $ref: "#/components/responses/RateLimitExceeded"

components:
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: توکن احراز هویت به صورت `Token <token>`.
    KeyAuth:
      type: apiKey
      in: header
      name: Nobitex-Key
      description: کلید عمومی API Key.
    SignatureAuth:
      type: apiKey
      in: header
      name: Nobitex-Signature
      description: امضای Ed25519 به صورت URL-safe Base64.
    TimestampAuth:
      type: apiKey
      in: header
      name: Nobitex-Timestamp
      description: زمان Unix بر حسب ثانیه در UTC.

  parameters:
    TraderBotUserAgent:
      name: User-Agent
      in: header
      required: false
      description: |
        برای شناسایی بات، این هدر را در همه درخواست‌های HTTP بات با الگوی
        `TraderBot/<name-and-version>` ارسال کنید. این هدر هنگام ورود خودکار با
        `captcha=api` الزامی و در سایر فراخوانی‌های بات اکیداً توصیه می‌شود.
      schema:
        type: string
      example: TraderBot/MyBot-1.0.0

    PublicKey:
      name: publicKey
      in: path
      required: true
      description: کلید عمومی API Key، همان مقدار فیلد `key`.
      schema:
        type: string
      example: 5XOCQZSPLQM4MiLzuUnZoBuqgYgTKl40W2X5j1pxfIA=
    XTOTP:
      name: X-TOTP
      in: header
      required: true
      description: کد دوعاملی کاربر.
      schema:
        type: string
      example: "123456"

  responses:
    RateLimitExceeded:
      description: محدودیت تعداد درخواست‌ها
      content:
        application/json:
          schema:
            type: object
            required:
              - status
              - code
            properties:
              status:
                type: string
                enum: [failed]
                example: failed
              code:
                type: string
                example: TooManyRequests

  schemas:
    APIKeyCreateRequest:
      type: object
      required:
        - name
        - permissions
      properties:
        name:
          type: string
          maxLength: 1024
          description: نام کلید برای شناسایی توسط کاربر
          example: my-api-key
        description:
          type: string
          maxLength: 1000
          default: ""
          description: توضیح دلخواه
          example: API key for internal services
        permissions:
          type: string
          description: |
            دسترسی‌ها به صورت رشته جداشده با کاما.
            مقادیر مجاز: `READ`, `TRADE`, `WITHDRAW`, `DEPOSIT`, `ADDRESS_BOOK`, `OTP`, `VIP_CREDIT`.
          example: READ,TRADE
        ipAddressesWhitelist:
          type: array
          maxItems: 15
          description: لیست IPهای مجاز. در صورت خالی بودن، محدودیت IP اعمال نمی‌شود.
          items:
            $ref: "#/components/schemas/IPAddress"
          default: []
        expirationDate:
          type: string
          format: date-time
          nullable: true
          description: تاریخ انقضای اختیاری. باید در آینده باشد.

    APIKeyUpdateRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 1024
        description:
          type: string
          maxLength: 1000
        ipAddressesWhitelist:
          type: array
          maxItems: 15
          items:
            $ref: "#/components/schemas/IPAddress"

    APIKey:
      type: object
      required:
        - key
        - name
        - description
        - permissions
        - ipAddressesWhitelist
        - expirationDate
        - createdAt
        - updatedAt
      properties:
        key:
          type: string
          description: کلید عمومی API Key
        name:
          type: string
        description:
          type: string
        permissions:
          type: string
          example: READ,TRADE
        ipAddressesWhitelist:
          type: array
          items:
            $ref: "#/components/schemas/IPAddress"
        expirationDate:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    IPAddress:
      oneOf:
        - type: string
          format: ipv4
        - type: string
          format: ipv6
      description: آدرس معتبر IPv4 یا IPv6.
      example: 192.168.1.10

    APIKeyCreateResponse:
      type: object
      required:
        - status
        - privateKey
        - key
      properties:
        status:
          type: string
          example: ok
        privateKey:
          type: string
          description: کلید خصوصی؛ فقط در پاسخ ساخت کلید نمایش داده می‌شود.
        key:
          $ref: "#/components/schemas/APIKey"

    APIKeyListResponse:
      type: object
      required:
        - status
        - keys
      properties:
        status:
          type: string
          example: ok
        keys:
          type: array
          items:
            $ref: "#/components/schemas/APIKey"

    APIKeyUpdateResponse:
      type: object
      required:
        - status
        - key
      properties:
        status:
          type: string
          example: ok
        key:
          $ref: "#/components/schemas/APIKey"

    StatusOnlyResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          example: ok

    APIKeyFailedResponse:
      type: object
      required:
        - status
        - code
        - message
      properties:
        status:
          type: string
          example: failed
        code:
          type: string
          example: ParseError
        message:
          type: string
          example: Validation Failed