> ## Documentation Index
> Fetch the complete documentation index at: https://altostrat.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List valid coupons for an instance

> Retrieves a list of all valid (unredeemed and not expired) coupons for a specific captive portal instance.



## OpenAPI

````yaml /api/en/captive-portal.yaml get /captive/instances/{instanceId}/coupons
openapi: 3.0.3
info:
  title: Altostrat Captive Portal API
  version: 1.0.0
  description: >-
    The Altostrat Captive Portal API is the microservice responsible for
    managing user authentication, access control, and branding for guest Wi-Fi
    networks.


    It acts as the control plane for guest network experiences on MikroTik
    devices within the Altostrat SDX platform, integrating with network
    automation to dynamically manage user sessions and access policies.


    This API allows you to programmatically manage:

    - **Instances:** A complete configuration for a captive portal, including
    its appearance (theme), authentication method (OAuth2 or coupon-based), and
    session rules.

    - **Auth Integrations:** Reusable configurations for third-party identity
    providers (e.g., Google, Azure AD) used in OAuth2 authentication strategies.

    - **Coupons & Schedules:** Time-limited access codes and the automated
    schedules that generate them for coupon-based guest access.

    - **Walled Garden:** Granular rules defining which domains or IP addresses
    users can access *before* authenticating, essential for identity provider
    logins.


    Developers use this API to programmatically create, configure, and manage
    bespoke guest Wi-Fi experiences across their entire network of sites.
servers:
  - url: https://v1.api.altostrat.io
    description: Altostrat Production API
security:
  - bearerAuth: []
tags:
  - name: Captive Portal Instances
    description: >-
      Manage captive portal configurations, including themes, authentication
      strategies, and associated sites.
  - name: Auth Integrations
    description: >-
      Configure third-party Identity Providers (IDPs) for OAuth2-based
      authentication.
  - name: Coupons
    description: Generate and manage single-use access coupons for guest networks.
  - name: Coupon Schedules
    description: Automate the generation of access coupons on a recurring schedule.
  - name: Walled Garden
    description: Control which destinations users can access before authentication.
  - name: Site Users
    description: >-
      View and manage users who have authenticated through the captive portal at
      a specific site.
  - name: Public Coupon URLs
    description: Signed public URLs for coupon schedule exports.
paths:
  /captive/instances/{instanceId}/coupons:
    get:
      tags:
        - Coupons
      summary: List valid coupons for an instance
      description: >-
        Retrieves a list of all valid (unredeemed and not expired) coupons for a
        specific captive portal instance.
      operationId: listCoupons
      parameters:
        - $ref: '#/components/parameters/instanceId'
      responses:
        '200':
          description: A list of valid coupons.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Coupon'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    instanceId:
      name: instanceId
      in: path
      required: true
      description: The unique identifier for the captive portal instance.
      schema:
        type: string
        format: uuid
        example: 9a7f1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c
  schemas:
    Coupon:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier for the coupon.
          example: b1c2d3e4-f5a6-b7c8-d9e0-f1a2b3c4d5e6
        code:
          type: string
          description: The 6-character alphanumeric code for the coupon.
          example: 8B7W3D
        expires_at:
          type: string
          format: date-time
          description: The timestamp when the coupon will expire and become invalid.
          example: '2025-11-01T12:00:00Z'
        redeemed_at:
          type: string
          format: date-time
          description: >-
            The timestamp when the coupon was redeemed. Null if not yet
            redeemed.
          nullable: true
          example: null
        created_at:
          type: string
          format: date-time
          description: The timestamp when the coupon was created.
          example: '2025-10-29T12:00:00Z'
    ErrorResponse:
      type: object
      properties:
        type:
          type: string
          description: A broad category for the error (e.g., 'invalid_request_error').
          example: invalid_request_error
        code:
          type: string
          description: A short, unique string identifying the specific error.
          example: parameter_missing
        message:
          type: string
          description: A human-readable description of what went wrong.
          example: The 'name' parameter is required for this request.
        doc_url:
          type: string
          description: >-
            A direct link to the documentation page for this specific error
            code.
          example: https://docs.altostrat.io/errors/parameter_missing
  responses:
    Unauthorized:
      description: >-
        Unauthorized - The request requires authentication, but no valid
        credentials were provided. Ensure your API key is correct and included
        in the 'Authorization' header.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: >-
        Not Found - The requested resource could not be found. Check that the
        provided ID is correct.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        API Key authentication. Provide your token in the 'Authorization'
        header. Example: `Authorization: Bearer <YOUR_TOKEN>`

````