openapi: 3.0.3
info:
  title: IssueBadge API
  description: |
    IssueBadge API provides comprehensive badge management and issuance functionality with multi-tenant support.
    
    ## Authentication
    The API supports two authentication methods:
    - **API Key Authentication**: Personal access tokens for direct API access
    - **OAuth2**: Bearer tokens for third-party integrations
    
    ## Multi-tenancy
    All operations are tenant-isolated. Each authenticated user can only access their own organization's data.
    
    ## Idempotency
    Badge creation and issuance operations require an `idempotency_key` to prevent duplicate submissions.
    
    ## Rate Limiting
    API requests are rate-limited per tenant to ensure fair usage and system stability.
    
    ## Base URLs
    - **Production**: `https://app.issuebadge.com/api/v1`
    - **OAuth2**: `https://app.issuebadge.com/api/v1/oauth`
    
  version: 1.0.0
  contact:
    name: IssueBadge API Support
    url: https://app.issuebadge.com/support
    email: support@issuebadge.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://app.issuebadge.com/api/v1
    description: Production server (Sanctum Auth)
  - url: https://app.issuebadge.com/api/v1/oauth
    description: Production server (OAuth2 Auth)
  - url: http://localhost:8000/api/v1
    description: Development server (Sanctum Auth)

paths:
  /validate-key:
    post:
      tags:
        - Authentication
      summary: Validate API Key
      description: |
        Validates the provided API key and returns authentication status.
        This endpoint is used to verify the authenticity of API tokens before making other API calls.
      operationId: validateKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - api_key
              properties:
                api_key:
                  type: string
                  description: The API key to validate
                  example: "1|abcdef123456789..."
            examples:
              sanctum_token:
                summary: Sanctum Token Validation
                value:
                  api_key: "1|abcdef123456789abcdef123456789abcdef123456"
      responses:
        '200':
          description: API key validation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the API key is valid
                  message:
                    type: string
                    description: Validation result message
                  data:
                    type: object
                    properties:
                      valid:
                        type: boolean
                        description: Key validity status
                      user_id:
                        type: integer
                        description: Associated user ID
                      tenant_id:
                        type: integer
                        description: Associated tenant ID
              examples:
                valid_key:
                  summary: Valid API Key
                  value:
                    success: true
                    message: "API key is valid"
                    data:
                      valid: true
                      user_id: 123
                      tenant_id: 456
                invalid_key:
                  summary: Invalid API Key
                  value:
                    success: false
                    message: "Invalid API key"
                    data:
                      valid: false
        '400':
          description: Bad request - Missing or invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /badge/getall:
    get:
      tags:
        - Badges
      summary: Get All Badges
      description: |
        Retrieves all badges available to the authenticated user's organization.
        Returns a simplified list with badge IDs and names for easy selection.
        Limited to 100 badges per request for performance.
      operationId: getAllBadges
      security:
        - sanctum_auth: []
        - oauth2_auth: []
      responses:
        '200':
          description: List of badges
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: ""
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Encrypted badge ID
                          example: "YWJjZGVmZ2hpams"
                        name:
                          type: string
                          description: Badge name
                          example: "Web Development Certificate"
              examples:
                success_response:
                  summary: Successful response
                  value:
                    success: true
                    message: ""
                    data:
                      - id: "YWJjZGVmZ2hpams"
                        name: "Web Development Certificate"
                      - id: "bG1ub3BxcnN0dXY"
                        name: "Data Science Badge"
                      - id: "d3h5ejEyMzQ1Ng"
                        name: "Project Management Certification"
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /badge/create:
    post:
      tags:
        - Badges
      summary: Create New Badge
      description: |
        Creates a new badge template that can be issued to recipients.
        Supports custom fields, expiration dates, and organization branding.
      operationId: createBadge
      security:
        - sanctum_auth: []
        - oauth2_auth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - name
                - description
                - badge_logo
                - issuing_organization_name
                - idempotency_key
              properties:
                name:
                  type: string
                  description: Badge name
                  maxLength: 200
                  example: "Web Development Certificate"
                nickname:
                  type: string
                  description: Optional badge nickname
                  example: "WebDev Cert"
                description:
                  type: string
                  description: Badge description
                  example: "Awarded for completing the full-stack web development course"
                left_panel_description:
                  type: string
                  description: Additional description for left panel
                  example: "This certificate validates comprehensive web development skills"
                badge_logo:
                  type: string
                  format: binary
                  description: Badge logo image (jpeg,png,jpg,gif,svg, max 2048KB)
                issuing_organization_name:
                  type: string
                  description: Name of the issuing organization
                  maxLength: 200
                  example: "Tech Academy"
                organization_id:
                  type: string
                  description: Existing organization ID (optional)
                  example: "org_123456"
                comment:
                  type: string
                  description: Additional comments
                  maxLength: 200
                  example: "Issued upon course completion"
                expire_date:
                  type: string
                  format: date
                  description: Badge expiration date (YYYY-MM-DD)
                  example: "2025-12-31"
                idempotency_key:
                  type: string
                  description: Unique key to prevent duplicate badge creation
                  maxLength: 80
                  example: "badge_create_20241201_123456"
                custom_fields:
                  type: array
                  description: Custom fields for this badge
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Field name
                        example: "Completion Date"
                      type:
                        type: string
                        enum: [text, email, number, date]
                        default: text
                        description: Field type
                        example: "date"
                      required:
                        type: boolean
                        default: false
                        description: Whether field is required
                        example: true
            examples:
              basic_badge:
                summary: Basic Badge Creation
                value:
                  name: "Web Development Certificate"
                  description: "Awarded for completing the full-stack web development course"
                  issuing_organization_name: "Tech Academy"
                  idempotency_key: "badge_create_20241201_123456"
                  # badge_logo: [binary file]
      responses:
        '201':
          description: Badge created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  badgeId:
                    type: string
                    description: UUID of the created badge
                    example: "550e8400-e29b-41d4-a716-446655440000"
                  organizationId:
                    type: string
                    description: UUID of the organization
                    example: "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
              examples:
                success_response:
                  summary: Successful badge creation
                  value:
                    success: true
                    badgeId: "550e8400-e29b-41d4-a716-446655440000"
                    organizationId: "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
        '400':
          description: Bad request - Invalid parameters or duplicate idempotency key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Payload too large - Badge logo exceeds 2MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'

  /issue/create:
    post:
      tags:
        - Badge Issuance
      summary: Issue Badge to Recipient
      description: |
        Issues a badge to a specific recipient. Sends notification email and creates a public verification URL.
        Supports custom field values and metadata for personalization.
      operationId: issueBadge
      security:
        - sanctum_auth: []
        - oauth2_auth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - badge_id
                - name
                - idempotency_key
              properties:
                badge_id:
                  type: string
                  description: Encrypted badge ID from badge creation
                  example: "YWJjZGVmZ2hpams"
                name:
                  type: string
                  description: Recipient's full name
                  maxLength: 200
                  example: "John Doe"
                email:
                  type: string
                  format: email
                  description: Recipient's email address (optional)
                  example: "john.doe@example.com"
                phone:
                  type: string
                  description: Recipient's phone number (optional)
                  example: "+1-555-123-4567"
                idempotency_key:
                  type: string
                  description: Unique key to prevent duplicate issuance
                  maxLength: 100
                  example: "issue_20241201_johndoe_123456"
                metadata:
                  type: object
                  description: Custom field values and additional metadata
                  example:
                    completion_date: "2024-11-30"
                    score: "95%"
                    course_duration: "12 weeks"
                    instructor: "Jane Smith"
            examples:
              basic_issuance:
                summary: Basic Badge Issuance
                value:
                  badge_id: "YWJjZGVmZ2hpams"
                  name: "John Doe"
                  email: "john.doe@example.com"
                  idempotency_key: "issue_20241201_johndoe_123456"
              with_metadata:
                summary: Badge Issuance with Custom Fields
                value:
                  badge_id: "YWJjZGVmZ2hpams"
                  name: "John Doe"
                  email: "john.doe@example.com"
                  phone: "+1-555-123-4567"
                  idempotency_key: "issue_20241201_johndoe_123456"
                  metadata:
                    completion_date: "2024-11-30"
                    score: "95%"
                    course_duration: "12 weeks"
                    instructor: "Jane Smith"
      responses:
        '201':
          description: Badge issued successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  IssueId:
                    type: string
                    description: Encrypted issue ID for tracking
                    example: "aXNzdWVfMTIzNDU2Nzg5MA"
                  publicUrl:
                    type: string
                    format: uri
                    description: Public URL for badge verification
                    example: "https://app.issuebadge.com/public/issue/aXNzdWVfMTIzNDU2Nzg5MA"
              examples:
                success_response:
                  summary: Successful badge issuance
                  value:
                    success: true
                    IssueId: "aXNzdWVfMTIzNDU2Nzg5MA"
                    publicUrl: "https://app.issuebadge.com/public/issue/aXNzdWVfMTIzNDU2Nzg5MA"
        '400':
          description: Bad request - Invalid parameters or duplicate idempotency key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Badge not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'

components:
  securitySchemes:
    sanctum_auth:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: Personal access token for API authentication
    oauth2_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth2 bearer token

  schemas:
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          description: Error message
          example: "An error occurred"
        error:
          type: string
          description: Detailed error information
          example: "Invalid authentication token"

    ValidationErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: "Validation failed"
        errors:
          type: object
          description: Field-specific validation errors
          example:
            name: ["The name field is required"]
            email: ["The email field must be a valid email address"]

    Badge:
      type: object
      properties:
        id:
          type: string
          description: Encrypted badge ID
          example: "YWJjZGVmZ2hpams"
        name:
          type: string
          description: Badge name
          example: "Web Development Certificate"
        description:
          type: string
          description: Badge description
          example: "Awarded for completing the full-stack web development course"
        issuing_organization_name:
          type: string
          description: Issuing organization name
          example: "Tech Academy"
        created_at:
          type: string
          format: date-time
          description: Badge creation timestamp
          example: "2024-01-15T10:30:00Z"

    IssuedBadge:
      type: object
      properties:
        id:
          type: string
          description: Encrypted issue ID
          example: "aXNzdWVfMTIzNDU2Nzg5MA"
        name:
          type: string
          description: Recipient name
          example: "John Doe"
        email:
          type: string
          description: Recipient email
          example: "john.doe@example.com"
        badge_name:
          type: string
          description: Badge name
          example: "Web Development Certificate"
        issue_date:
          type: string
          format: date
          description: Issuance date
          example: "2024-01-15"
        public_url:
          type: string
          format: uri
          description: Public verification URL
          example: "https://app.issuebadge.com/public/issue/aXNzdWVfMTIzNDU2Nzg5MA"

tags:
  - name: Authentication
    description: API key validation and authentication
  - name: Badges
    description: Badge template management
  - name: Badge Issuance
    description: Badge issuance and recipient management

externalDocs:
  description: Find more info about IssueBadge
  url: https://app.issuebadge.com/docs