> ## 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. # Create a captive portal instance > Creates a new captive portal instance with a basic configuration. Further details, such as themes and sites, can be added via an update operation. ## OpenAPI ````yaml /api/en/captive-portal.yaml post /captive/instances 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: post: tags: - Captive Portal Instances summary: Create a captive portal instance description: >- Creates a new captive portal instance with a basic configuration. Further details, such as themes and sites, can be added via an update operation. operationId: createInstance requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InstanceCreate' responses: '201': description: The captive portal instance was created successfully. content: application/json: schema: $ref: '#/components/schemas/Instance' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/ServerError' components: schemas: InstanceCreate: type: object required: - name - strategy - session_ttl properties: name: type: string description: A human-readable name for the instance. example: Main Office Guest WiFi strategy: type: string description: The authentication method for this captive portal. enum: - oauth2 - coupon example: oauth2 session_ttl: type: integer description: >- The duration in seconds that a user's session remains active after authentication. Minimum 1200, maximum 604800. example: 43200 auth_integration_id: type: string format: uuid description: >- Required if strategy is 'oauth2'. The ID of a pre-configured authentication integration. nullable: true example: c4d5e6f7-8a9b-0c1d-2e3f-4a5b6c7d8e9f Instance: type: object properties: id: type: string format: uuid description: The unique identifier for the instance. example: 9a7f1b2c-3d4e-5f6a-7b8c-9d0e1f2a3b4c auth_integration_id: type: string format: uuid description: >- The ID of the authentication integration used if the strategy is 'oauth2'. Null for 'coupon' strategy. nullable: true example: c4d5e6f7-8a9b-0c1d-2e3f-4a5b6c7d8e9f strategy: type: string description: The authentication method for this captive portal. enum: - oauth2 - coupon example: oauth2 name: type: string description: A human-readable name for the instance. example: Main Office Guest WiFi session_ttl: type: integer description: >- The duration in seconds that a user's session remains active after successful authentication. example: 43200 auth_window_ttl: type: integer description: >- For OAuth2 strategy, the duration in seconds that the walled garden is temporarily opened to allow the user to complete authentication with the identity provider. example: 300 theme: type: object description: A collection of branding and appearance settings. properties: logo: type: string format: uri description: The URL for the logo image displayed on the portal. nullable: true example: >- https://v1.api.altostrat.io/captive/assets/.../logo_abc123.png?signature=... icon: type: string format: uri description: The URL for the favicon/icon for the portal page. nullable: true example: >- https://v1.api.altostrat.io/captive/assets/.../icon_def456.png?signature=... accent_text: type: string description: >- The hex color code for text on accented elements (e.g., buttons). example: '#FFFFFF' accent_color: type: string description: >- The hex color code for primary accented elements (e.g., buttons, links). example: '#0396d5' text_color: type: string description: The hex color code for primary body text. example: '#4f4f4f' secondary_text_color: type: string description: The hex color code for secondary, less prominent text. example: '#8f8f8f' background_color: type: string description: The hex color code for the page background. example: '#f9f9f9' border_color: type: string description: The hex color code for borders on elements like input fields. example: '#e0e0e0' box_color: type: string description: The hex color code for the background of container boxes. example: '#ffffff' terms_text: type: string description: >- The text of the terms and conditions that can be displayed to the user. nullable: true example: By connecting, you agree to our terms of service... sites: type: array description: >- A list of sites and their subnets where this captive portal instance is active. items: $ref: '#/components/schemas/Site' created_at: type: string format: date-time description: The timestamp when the instance was created. example: '2025-10-29T12:00:00Z' preview_url: type: string format: uri description: A temporary, signed URL to preview the captive portal's appearance. nullable: true example: https://captive.altostr.at/preauth?token=eyJpdiI6... Site: type: object properties: id: type: string format: uuid description: The unique identifier for the site. example: a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6 subnets: type: array description: >- An array of subnets within this site where the captive portal is active. items: type: string description: An IPv4 subnet in CIDR notation. example: 192.168.88.0/24 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: BadRequest: description: >- Bad Request - The request was malformed or invalid. This can happen if a required parameter is missing or a value is of the wrong type. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' 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' Forbidden: description: >- Forbidden - You do not have permission to perform this action on the requested resource. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServerError: description: >- Internal Server Error - Something went wrong on our end. We've been notified and are looking into it. 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 ` ````