# List audit log events Source: https://altostrat.io/docs/api/en/audit-logs/list-audit-log-events api/en/audit-logs.yaml get /audit-logs Retrieve a list of audit log events for your organization. This endpoint supports powerful filtering and pagination to help you find specific events for security, compliance, or debugging purposes. Results are returned in reverse chronological order (most recent first) by default. # Create a billing account Source: https://altostrat.io/docs/api/en/billing-accounts/create-a-billing-account api/en/workspaces.yaml post /workspaces/{workspaceId}/billing-accounts Creates a new billing account within a workspace. This also creates a corresponding Customer object in Stripe. The behavior is constrained by the workspace's billing mode; for `single` mode, only one billing account can be created. For `pooled` and `assigned` modes, up to 10 can be created. # Delete a billing account Source: https://altostrat.io/docs/api/en/billing-accounts/delete-a-billing-account api/en/workspaces.yaml delete /workspaces/{workspaceId}/billing-accounts/{billingAccountId} Permanently deletes a billing account. This action cannot be undone. A billing account cannot be deleted if it has any active subscriptions. # List billing accounts Source: https://altostrat.io/docs/api/en/billing-accounts/list-billing-accounts api/en/workspaces.yaml get /workspaces/{workspaceId}/billing-accounts Returns a list of billing accounts associated with a workspace. # Retrieve a billing account Source: https://altostrat.io/docs/api/en/billing-accounts/retrieve-a-billing-account api/en/workspaces.yaml get /workspaces/{workspaceId}/billing-accounts/{billingAccountId} Retrieves the details of a specific billing account. # Update a billing account Source: https://altostrat.io/docs/api/en/billing-accounts/update-a-billing-account api/en/workspaces.yaml patch /workspaces/{workspaceId}/billing-accounts/{billingAccountId} Updates the details of a billing account. Any parameters not provided will be left unchanged. This operation also updates the corresponding Customer object in Stripe. # JSON Web Key Set (JWKS) Endpoint Source: https://altostrat.io/docs/api/en/discovery/json-web-key-set-jwks-endpoint api/en/authentication.yaml get /.well-known/jwks.json Provides the set of public keys used to verify the signature of JWTs issued by the authentication server. Clients should use the `kid` (Key ID) from a JWT's header to select the correct key for validation. # OIDC Discovery Endpoint Source: https://altostrat.io/docs/api/en/discovery/oidc-discovery-endpoint api/en/authentication.yaml get /.well-known/openid-configuration Returns a JSON document containing the OpenID Provider's configuration metadata. OIDC-compliant clients use this endpoint to automatically discover the locations of the authorization, token, userinfo, and JWKS endpoints, as well as all supported capabilities. # API Introduction Source: https://altostrat.io/docs/api/en/introduction Welcome to the Altostrat SDX API. Learn about our core concepts, authentication, and how to make your first API call to start automating your network. Welcome to the Altostrat SDX Developer API! Our API is your gateway to programmatically managing your entire network fleet, building powerful integrations, and leveraging our advanced automation and agentic AI capabilities. The API is built on standard REST principles, using predictable resource-oriented URLs and standard HTTP response codes. All requests and responses are encoded in JSON. The base URL for all API endpoints is `https://api.altostrat.io`. ```mermaid theme={null} graph LR subgraph "Your Application" A[Your Script or Service] end subgraph "Altostrat Platform" B(api.altostrat.io); M1[Sites & Devices]; M2[Security & Policies]; M3[Automation & AI]; M4[Monitoring & Billing]; end A -- "Authenticated HTTPS Request" --> B; B --> M1 & M2 & M3 & M4; ``` ## Authentication The Altostrat API uses two types of Bearer Tokens for authentication. All authenticated requests must include the token in the `Authorization` header. `Authorization: Bearer YOUR_TOKEN` **Use for:** Backend services, scripts, and CI/CD automation. API Keys are long-lived, secure tokens that are not tied to a specific user session. They are the recommended method for any programmatic, non-interactive integration. You can generate and manage your API keys from the **Automation → Vault** section of the SDX dashboard. **Use for:** Frontend applications or third-party integrations where actions need to be performed on behalf of a logged-in user. These are standard, short-lived JSON Web Tokens obtained through our OIDC-compliant authentication flow. They carry the permissions and context of the authenticated user. ## Your First API Call This quickstart will guide you through making your first API call using a long-lived API Key. Navigate to **Automation → Vault** in your SDX dashboard. 1. Click **+ Add Item**. 2. For the **Name**, use the prefix `api-key:` followed by a description (e.g., `api-key:my-first-integration`). 3. Leave the **Secret Value** field blank. 4. Click **Save**. The system will generate a secure API key and display it to you **once**. Copy this key and store it securely. Use the `curl` command below in your terminal, replacing `YOUR_API_KEY` with the key you just copied. This will make an authenticated request to list all the sites in your workspace. ```bash curl theme={null} curl -X GET "https://api.altostrat.io/sites" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" ``` ```json Response theme={null} { "status": "success", "data": [ { "site_id": "site-abc123def456", "name": "Main Office Router" } ] } ``` ## Core Architectural Concepts ### Synchronous vs. Asynchronous Operations Our API provides two distinct modes of execution for different types of tasks. **For immediate, real-time data.** Synchronous endpoints (e.g., `/sites/{id}/commands/synchronous`) execute a read-only command directly on a device and return the result in the same API call. **Use for:** Running a live `ping`, getting the current status of an interface, or any task where you need an immediate response. **For tasks that take time or make changes.** Asynchronous endpoints (e.g., `/sites/{id}/commands/asynchronous`) accept a task, queue it for reliable background execution, and immediately return a `202 Accepted` response. **Use for:** Executing a script across multiple sites or applying a new policy. You can provide an optional `notify_url` (webhook) to be notified when the job is complete. ### Common API Patterns All API errors return a consistent JSON object with a `type`, `code`, `message`, and a `doc_url` linking to the relevant documentation. ```json theme={null} { "type": "invalid_request_error", "code": "resource_missing", "message": "No site found with the ID 'site-xyz789'.", "doc_url": "https://docs.altostrat.io/errors/resource_missing" } ``` Endpoints that can return large lists of items are paginated. Use the `cursor` or `page` query parameters as specified in each endpoint's documentation to navigate through results. ## API At a Glance Our API is organized into logical groups of resources. Explore the sections below to find the endpoints you need. Manage workspaces, organizations, users, billing, and subscriptions. Interact with sites, run jobs, manage backups, and access device-level data. Configure WAN Failover, Managed VPNs, and Captive Portals. Manage Security Groups, Prefix Lists, DNS Filtering, and BGP Threat Mitigation. Build workflows, manage scripts, use the Vault, and interact with our AI Co-pilot. Retrieve faults, generate SLA reports, and access real-time metrics. # List invoices Source: https://altostrat.io/docs/api/en/invoices/list-invoices api/en/workspaces.yaml get /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/invoices Returns a list of invoices for a billing account. Invoices are returned in reverse chronological order. # Preview an invoice Source: https://altostrat.io/docs/api/en/invoices/preview-an-invoice api/en/workspaces.yaml post /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/invoices/preview Previews an upcoming invoice for a billing account, showing the financial impact of potential subscription changes, such as adding products or changing quantities. This does not modify any existing subscriptions. # Cancel a Pending Job Source: https://altostrat.io/docs/api/en/jobs/cancel-a-pending-job api/en/mikrotik-api.yaml delete /sites/{siteId}/jobs/{jobId} Deletes a job that has not yet started execution. Jobs that are in progress, completed, or failed cannot be deleted. # Create a Job for a Site Source: https://altostrat.io/docs/api/en/jobs/create-a-job-for-a-site api/en/mikrotik-api.yaml post /sites/{siteId}/jobs Creates and queues a new job to be executed on the specified site. The job's payload is a raw RouterOS script, and metadata is provided via headers. # List Jobs for a Site Source: https://altostrat.io/docs/api/en/jobs/list-jobs-for-a-site api/en/mikrotik-api.yaml get /sites/{siteId}/jobs Retrieves a list of all jobs that have been created for a specific site, ordered by creation date (most recent first). # Retrieve a Job Source: https://altostrat.io/docs/api/en/jobs/retrieve-a-job api/en/mikrotik-api.yaml get /sites/{siteId}/jobs/{jobId} Retrieves the complete details of a specific job by its unique identifier (UUID). # Exchange Code or Refresh Token for Tokens Source: https://altostrat.io/docs/api/en/oauth-20-&-oidc/exchange-code-or-refresh-token-for-tokens api/en/authentication.yaml post /oauth/token Used to exchange an `authorization_code` for tokens, or to use a `refresh_token` to get a new `access_token`. Client authentication can be performed via `client_secret_post` (in the body), `client_secret_basic` (HTTP Basic Auth), or `private_key_jwt`. # Get User Profile Source: https://altostrat.io/docs/api/en/oauth-20-&-oidc/get-user-profile api/en/authentication.yaml get /userinfo Retrieves the profile of the user associated with the provided `access_token`. The claims returned are based on the scopes granted during authentication. # Initiate User Authentication Source: https://altostrat.io/docs/api/en/oauth-20-&-oidc/initiate-user-authentication api/en/authentication.yaml get /authorize This is the starting point for user authentication. The Altostrat web application redirects the user's browser to this endpoint to begin the OAuth 2.0 Authorization Code Flow with PKCE. # Log Out User (Legacy) Source: https://altostrat.io/docs/api/en/oauth-20-&-oidc/log-out-user-legacy api/en/authentication.yaml get /v2/logout Logs the user out of their Altostrat session and redirects them back to a specified URL. # Log Out User (OIDC Compliant) Source: https://altostrat.io/docs/api/en/oauth-20-&-oidc/log-out-user-oidc-compliant api/en/authentication.yaml get /oidc/logout This endpoint conforms to the OIDC Session Management specification. It logs the user out and can redirect them back to the application. # Revoke Token Source: https://altostrat.io/docs/api/en/oauth-20-&-oidc/revoke-token api/en/authentication.yaml post /oauth/revoke Revokes an `access_token` or `refresh_token`, invalidating it immediately. This is useful for scenarios like password changes or user-initiated logouts from all devices. # Create a child organization Source: https://altostrat.io/docs/api/en/organizations/create-a-child-organization api/en/workspaces.yaml post /workspaces/{workspaceId}/organizations/{organizationId}/children Creates a new organization as a direct child of the specified parent organization. The hierarchy cannot exceed 10 levels of depth, and a parent cannot have more than 100 direct children. # Create an organization Source: https://altostrat.io/docs/api/en/organizations/create-an-organization api/en/workspaces.yaml post /workspaces/{workspaceId}/organizations Creates a new top-level organization within a workspace. To create a child organization, use the `/organizations/{organizationId}/children` endpoint. A workspace cannot have more than 1,000 organizations in total. # Delete an organization Source: https://altostrat.io/docs/api/en/organizations/delete-an-organization api/en/workspaces.yaml delete /workspaces/{workspaceId}/organizations/{organizationId} Permanently deletes an organization. An organization cannot be deleted if it or any of its descendants have active resource usage. # Export organization usage as CSV Source: https://altostrat.io/docs/api/en/organizations/export-organization-usage-as-csv api/en/workspaces.yaml get /workspaces/{workspaceId}/organizations/usage.csv Generates and downloads a CSV file detailing the resource usage and limits for all organizations within the specified workspace. # Export organization usage as PDF Source: https://altostrat.io/docs/api/en/organizations/export-organization-usage-as-pdf api/en/workspaces.yaml get /workspaces/{workspaceId}/organizations/usage.pdf Generates and downloads a PDF file detailing the resource usage and limits for all organizations within the specified workspace. # List all descendant organizations Source: https://altostrat.io/docs/api/en/organizations/list-all-descendant-organizations api/en/workspaces.yaml get /workspaces/{workspaceId}/organizations/{organizationId}/descendants Returns a flat list of all organizations that are descendants (children, grandchildren, etc.) of the specified parent organization. # List child organizations Source: https://altostrat.io/docs/api/en/organizations/list-child-organizations api/en/workspaces.yaml get /workspaces/{workspaceId}/organizations/{organizationId}/children Returns a list of immediate child organizations of a specified parent organization. # List organizations Source: https://altostrat.io/docs/api/en/organizations/list-organizations api/en/workspaces.yaml get /workspaces/{workspaceId}/organizations Returns a list of all organizations within the specified workspace. # Retrieve an organization Source: https://altostrat.io/docs/api/en/organizations/retrieve-an-organization api/en/workspaces.yaml get /workspaces/{workspaceId}/organizations/{organizationId} Retrieves the details of a specific organization within a workspace. # Retrieve organization limits Source: https://altostrat.io/docs/api/en/organizations/retrieve-organization-limits api/en/workspaces.yaml get /workspaces/{workspaceId}/organizations/{organizationId}/limits Retrieves a detailed breakdown of usage, limits, and available capacity for each meterable product type for a specific organization. This takes into account the organization's own limits, limits inherited from its parents, and the total capacity available from its subscription. # Retrieve parent organization Source: https://altostrat.io/docs/api/en/organizations/retrieve-parent-organization api/en/workspaces.yaml get /workspaces/{workspaceId}/organizations/{organizationId}/parent Retrieves the parent organization of a specified child organization. If the organization is at the top level, this endpoint will return a 204 No Content response. # Update an organization Source: https://altostrat.io/docs/api/en/organizations/update-an-organization api/en/workspaces.yaml patch /workspaces/{workspaceId}/organizations/{organizationId} Updates specified attributes of an organization. This endpoint can be used to change the organization's name, update its resource limits, or modify branding settings. You only need to provide the fields you want to change. # Create a Setup Intent Source: https://altostrat.io/docs/api/en/payment-methods/create-a-setup-intent api/en/workspaces.yaml post /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/payment-methods Creates a Stripe Setup Intent to collect payment method details for future payments. This returns a `client_secret` that you can use with Stripe.js or the mobile SDKs to display a payment form. A billing account cannot have more than 5 payment methods. # Detach a payment method Source: https://altostrat.io/docs/api/en/payment-methods/detach-a-payment-method api/en/workspaces.yaml delete /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/payment-methods/{paymentMethodId} Detaches a payment method from a billing account. You cannot detach the only payment method on an account, nor can you detach the default payment method if there are active subscriptions. # List payment methods Source: https://altostrat.io/docs/api/en/payment-methods/list-payment-methods api/en/workspaces.yaml get /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/payment-methods Returns a list of payment methods attached to a billing account. # Set default payment method Source: https://altostrat.io/docs/api/en/payment-methods/set-default-payment-method api/en/workspaces.yaml put /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/payment-methods/{paymentMethodId} Sets a specified payment method as the default for a billing account. This payment method will be used for all future subscription invoices. # Get public branding information Source: https://altostrat.io/docs/api/en/public/get-public-branding-information api/en/workspaces.yaml get /organizations/{id}/branding Retrieves the public branding information for an organization, such as its display name, logo, and theme colors. You can use either the organization's primary ID (`org_...`) or its external UUID as the identifier. This is a public, unauthenticated endpoint. # Resolve login hint Source: https://altostrat.io/docs/api/en/public/resolve-login-hint api/en/workspaces.yaml get /organizations/resolve/{login_hint} Given a unique login hint (e.g., a short company name like 'acme'), this endpoint returns the corresponding organization ID. This is useful for pre-filling organization details in a login flow. This is a public, unauthenticated endpoint. # Delete a Site Source: https://altostrat.io/docs/api/en/sites/delete-a-site api/en/mikrotik-api.yaml delete /sites/{siteId} Schedules a site for deletion. The device will be sent a command to remove its bootstrap scheduler, and after a grace period, the site record and all associated data will be permanently removed. # List Recent Sites Source: https://altostrat.io/docs/api/en/sites/list-recent-sites api/en/mikrotik-api.yaml get /sites/recent Returns a list of the 5 most recently accessed sites for the authenticated user, ordered by most recent access. # List Sites Source: https://altostrat.io/docs/api/en/sites/list-sites api/en/mikrotik-api.yaml get /sites Retrieves a paginated list of all MikroTik sites associated with the authenticated user's workspace. # List Sites (Minimal) Source: https://altostrat.io/docs/api/en/sites/list-sites-minimal api/en/mikrotik-api.yaml get /site-minimal Retrieves a condensed list of MikroTik sites, suitable for UI elements like navigation menus where only essential information is needed. # Retrieve a Site Source: https://altostrat.io/docs/api/en/sites/retrieve-a-site api/en/mikrotik-api.yaml get /sites/{siteId} Retrieves the complete details of a specific MikroTik site by its unique identifier (UUID). # Update a Site Source: https://altostrat.io/docs/api/en/sites/update-a-site api/en/mikrotik-api.yaml patch /sites/{siteId} Updates the mutable properties of a site, such as its name, location, or timezone. Only the fields provided in the request body will be updated. # Cancel a subscription Source: https://altostrat.io/docs/api/en/subscriptions/cancel-a-subscription api/en/workspaces.yaml delete /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/subscriptions/{subscriptionId} Cancels a subscription at the end of the current billing period. This operation cannot be performed if it would leave the workspace or billing account with insufficient capacity for its current resource usage. # Check trial eligibility Source: https://altostrat.io/docs/api/en/subscriptions/check-trial-eligibility api/en/workspaces.yaml get /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/trial-eligibility Checks if a workspace is eligible for a 14-day free trial. A workspace is eligible if it has only one billing account and no existing subscriptions. # Create a subscription Source: https://altostrat.io/docs/api/en/subscriptions/create-a-subscription api/en/workspaces.yaml post /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/subscriptions Creates a new Stripe subscription for a billing account. If the workspace is eligible for a trial, a 14-day trial subscription is created without requiring a payment method. Otherwise, a default payment method must be present on the billing account. # List subscriptions Source: https://altostrat.io/docs/api/en/subscriptions/list-subscriptions api/en/workspaces.yaml get /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/subscriptions Returns a list of subscriptions associated with a billing account. # Retrieve a subscription Source: https://altostrat.io/docs/api/en/subscriptions/retrieve-a-subscription api/en/workspaces.yaml get /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/subscriptions/{subscriptionId} Retrieves the details of a specific subscription. # Update a subscription Source: https://altostrat.io/docs/api/en/subscriptions/update-a-subscription api/en/workspaces.yaml patch /workspaces/{workspaceId}/billing-accounts/{billingAccountId}/subscriptions/{subscriptionId} Updates a subscription. This endpoint supports multiple distinct operations. You can change product quantities, add or remove products, update metadata, or perform an action like `pause`, `resume`, or `sync`. Only one type of operation (e.g., `product_quantities`, `add_products`, `action`) is allowed per request. # Add a member to a workspace Source: https://altostrat.io/docs/api/en/workspace-members/add-a-member-to-a-workspace api/en/workspaces.yaml post /workspaces/{workspaceId}/members Adds a new user to a workspace with a specified role. Only workspace owners and admins can add new members. A workspace cannot have more than 100 members. # List workspace members Source: https://altostrat.io/docs/api/en/workspace-members/list-workspace-members api/en/workspaces.yaml get /workspaces/{workspaceId}/members Returns a list of users who are members of the specified workspace, including their roles. # Remove a member from a workspace Source: https://altostrat.io/docs/api/en/workspace-members/remove-a-member-from-a-workspace api/en/workspaces.yaml delete /workspaces/{workspaceId}/members/{memberId} Removes a member from a workspace. A user can remove themselves, or an owner/admin can remove other members. The last owner of a workspace cannot be removed. # Update a member's role Source: https://altostrat.io/docs/api/en/workspace-members/update-a-members-role api/en/workspaces.yaml patch /workspaces/{workspaceId}/members/{memberId} Updates the role of an existing member in a workspace. Role changes are subject to hierarchy rules; for example, an admin cannot promote another member to an owner. # Archive a workspace Source: https://altostrat.io/docs/api/en/workspaces/archive-a-workspace api/en/workspaces.yaml delete /workspaces/{workspaceId} Archives a workspace, preventing any further modifications. A workspace cannot be archived if it contains organizations with active resource usage or billing accounts with active subscriptions. This is a soft-delete operation. Only workspace owners can perform this action. # Create a workspace Source: https://altostrat.io/docs/api/en/workspaces/create-a-workspace api/en/workspaces.yaml post /workspaces Creates a new workspace, which acts as a top-level container for your resources, users, and billing configurations. The user creating the workspace is automatically assigned the 'owner' role. # List workspaces Source: https://altostrat.io/docs/api/en/workspaces/list-workspaces api/en/workspaces.yaml get /workspaces Returns a list of workspaces the authenticated user is a member of. # Retrieve a workspace Source: https://altostrat.io/docs/api/en/workspaces/retrieve-a-workspace api/en/workspaces.yaml get /workspaces/{workspaceId} Retrieves the details of an existing workspace. You must be a member of the workspace to retrieve it. # Update a workspace Source: https://altostrat.io/docs/api/en/workspaces/update-a-workspace api/en/workspaces.yaml patch /workspaces/{workspaceId} Updates the specified workspace by setting the values of the parameters passed. Any parameters not provided will be left unchanged. Only workspace owners and admins can perform this action. # Billing and Subscriptions Source: https://altostrat.io/docs/sdx/en/account/billing-and-subscriptions A complete guide to managing your subscriptions, payment methods, and invoices, and understanding how resource pooling and usage metering work in Altostrat SDX. Altostrat SDX uses a flexible, subscription-based billing model powered by Stripe. This guide explains the core components of our billing system and how to manage your account. ## The Billing Architecture Your workspace's resources are determined by a simple hierarchy of three components: * **Billing Account:** The central entity that holds your company's details, payment methods, and subscriptions. Each workspace can have one or more billing accounts, depending on its [Billing Mode](/sdx/en/account/workspaces-and-organizations). * **Subscription:** A recurring plan that provides a specific quantity of one or more **Products** to a Billing Account. * **Products:** The meterable resources you consume, such as `sites`, `users`, or `sso` connections. ### Resource Pooling All active subscriptions within a single Billing Account automatically combine their resources into a shared **Resource Pool**. This provides flexibility, allowing one team or project to use more resources than their specific subscription provides, as long as the total usage stays within the aggregated pool capacity. ```mermaid theme={null} graph LR subgraph "Billing Account" S1[Subscription A
50 sites, 10 users] S2[Subscription B
10 sites, 100 users] end subgraph "Available Resource Pool" Pool[Total Capacity
60 sites
110 users] end S1 -- contributes --> Pool S2 -- contributes --> Pool ``` ## The Subscription Lifecycle Subscriptions transition through several states based on payment status and user actions. ```mermaid theme={null} stateDiagram-v2 [*] --> Trialing: New eligible workspace created Trialing --> Active: Payment method added before trial ends Trialing --> Canceled: Trial ends without payment method Active --> Canceled: User cancels subscription Active --> Past_Due: Invoice payment fails Past_Due --> Active: Successful payment is made Past_Due --> Unpaid: Grace period ends without payment Unpaid --> Canceled: Subscription is terminated ``` ### 14-Day Free Trial New, eligible workspaces automatically start with a 14-day free trial, giving you full access to the platform's features. To ensure uninterrupted service, add a default payment method to your Billing Account before the trial period ends. ## Managing Your Billing Account All billing management is handled within the **Account → Billing** section of the SDX dashboard. ### Managing Subscriptions You can modify your active subscriptions at any time to align with your changing needs. * **To Change Quantities:** 1. Navigate to the **Subscriptions** tab and select the subscription you wish to modify. 2. Adjust the quantity for any product. * **Upgrades** (increasing quantity) take effect immediately and are pro-rated on your next invoice. * **Downgrades** (decreasing quantity) take effect at the start of your next billing cycle. You cannot decrease the quantity of a product below its current usage across your workspace. ### Managing Payment Methods Each Billing Account can have up to 5 payment methods on file, with one designated as the default. 1. Navigate to the **Payment Methods** tab. 2. From here, you can **Add** a new payment method, **Set as Default**, or **Delete** an existing one. It's a best practice to keep at least one backup payment method on file. If a payment fails on your default method, our system will automatically attempt to charge the backup methods to prevent service interruption. ### Accessing Invoices You can view and download your entire billing history. 1. Navigate to the **Invoices** tab. 2. You will see a list of all past invoices. 3. Click on any invoice to view its details or download a PDF for your records. ## Usage Metering and Limit Enforcement Altostrat uses a subscription-based metering system, not a pay-as-you-go model. This means your usage is tracked in real-time against the total capacity available in your resource pool. * **Real-Time Enforcement:** If an action would cause your usage to exceed the available capacity for a given product (e.g., adding a new site when you have no `sites` capacity left), the action will be blocked. * **Hierarchical Limits:** Usage is also validated against any limits set on your [Organizations](/sdx/en/account/workspaces-and-organizations). The most restrictive limit—whether from the subscription pool or an organization's configuration—always applies. # Account & Billing Source: https://altostrat.io/docs/sdx/en/account/introduction Learn how to build the foundational structure of your Altostrat environment, including managing organizations, workspaces, billing, and user access. Welcome to the Account & Billing section. The concepts covered here are the foundational blueprint for your entire Altostrat SDX environment. A well-structured account is the key to secure collaboration, scalable resource management, and clear financial oversight. This section will guide you through setting up your organizational hierarchy, managing user access with teams and roles, and configuring your billing and subscriptions. ## The Account Architecture Your entire Altostrat environment is built on a clear hierarchy of components that work together to provide a secure, multi-tenant foundation. ```mermaid theme={null} graph TD subgraph "Organization" Org[Your Company] end subgraph "Workspace" Ws[Primary Workspace] end subgraph "Billing" BA[Billing Account] --> SUB[Subscriptions]; end subgraph "Access Control" Team[Team A] --> U["User (with Role)"]; end subgraph "Network Resources" RES[Sites, Policies, etc.] end Org --> Ws; Ws --> BA; Ws --> Team; Team --> RES; ``` ## The Pillars of Account Management Model your business using a flexible hierarchy of **Organizations**, **Workspaces**, and **Teams**. This structure is the foundation for both resource allocation and access control, scaling from a single team to a global enterprise. Grant granular permissions to your **Users** by assigning them **Roles** within specific **Teams**. This ensures that team members have exactly the access they need to do their jobs, adhering to the principle of least privilege. Manage your resources through **Billing Accounts** and **Subscriptions**. Our system supports everything from a single, centralized billing account to complex, multi-tenant models for MSPs and franchises. ## In This Section Dive into the detailed guides for each component of your account's foundation. Learn how to model your business using Altostrat's hierarchical structure for resource and limit management. A complete guide to managing your subscriptions, payment methods, invoices, and resource pools. Learn how to add users, organize them into teams, and assign roles to control access. # User and Team Management Source: https://altostrat.io/docs/sdx/en/account/user-and-team-management Learn how to manage access control in Altostrat SDX by organizing users into teams and assigning roles to grant permissions to your network resources. Altostrat SDX uses a flexible Role-Based Access Control (RBAC) model to ensure secure and organized collaboration. Access to all resources, such as sites and policies, is managed through a hierarchy of **Users**, **Teams**, and **Roles**. ## The Access Control Model Understanding these three components is key to managing your workspace effectively. * **Users:** An individual account. A user can be a full team member with login access or a notification-only recipient. * **Teams:** The primary containers for collaboration. All resources (sites, policies, etc.) belong to a team. A user must be a member of a team to access its resources. * **Roles:** Collections of permissions (scopes) that define *what* a user can do. Roles are assigned to users *within a specific team*. ```mermaid theme={null} graph TD subgraph "Your Organization" T1[Team: NOC Team] T2[Team: Security Auditors] end subgraph "Resources" S1[Site A] S2[Site B] end subgraph "Users & Roles" U1[User: Alice] U2[User: Bob] U1 -- "Role: Administrator" --> T1 U2 -- "Role: Administrator" --> T1 U2 -- "Role: Read-Only" --> T2 end T1 --> S1 & S2 ``` In this example, both Alice and Bob are administrators in the "NOC Team" and can manage Sites A and B. Bob is also a member of the "Security Auditors" team, but with a "Read-Only" role, giving him different permissions in that context. ## Managing Teams Teams are the foundation of your workspace. You should create teams that align with your organizational structure or project responsibilities. ### Creating a New Team In the SDX dashboard, go to **Settings → Teams** and click **+ Add Team**. Provide a descriptive name, such as "Network Operations" or "Client XYZ Support", and confirm. The team is now created, with you as the owner. ### Switching Your Active Team If you belong to multiple teams, use the team switcher in the main navigation to change your active context. This determines which team's resources you are currently viewing and managing. ## Managing Users and Team Membership Once a team exists, you can add members and assign them roles. Go to **Settings → Teams**, select the team you want to manage, and click on the **Members** tab. Click **Add Member**. You can now either: * **Invite a new user** by entering their email address. They will receive an invitation to join your team. * **Add an existing Altostrat user** by searching for their name or email. Select one or more **Roles** to grant the user permissions within this team. The "Administrator" role provides broad access, while other roles may be more limited. You can create custom roles with specific permissions in **Settings → Roles & Permissions**. From the members list, you can edit a user's roles or remove them from the team. To edit a user's profile details (like their name or `allow_login` status), navigate to the global **Settings → Users** list. ## User Types: Full Access vs. Notification-Only When creating or editing a user, you can set their `allow_login` status. This creates two types of users: * **Portal Users (`allow_login: true`):** Full members who can log into the dashboard. * **Notification-Only Users (`allow_login: false`):** Cannot log in, but can be added as recipients in [Notification Groups](/sdx/en/monitoring/notifications). Ideal for stakeholders who need alerts but not platform access. ## Best Practices Assign roles that grant users only the permissions they need to perform their job. Avoid giving everyone administrative access. If a user's access needs to be revoked, it's often better to disable their login (`allow_login: false`) or remove them from a team rather than deleting their account entirely. This preserves their activity history for auditing purposes. # Workspaces and Organizations Source: https://altostrat.io/docs/sdx/en/account/workspaces-and-organizations Learn how to model your business with Altostrat's hierarchical structure, using Organizations, Workspaces, and Teams to manage billing, resources, and access control. Altostrat SDX provides a powerful and flexible hierarchical structure to model your business, whether you're a single entity, a large enterprise with multiple departments, or a managed service provider (MSP) with many clients. Understanding this structure is key to managing your resources, billing, and user access effectively. The hierarchy is built on three core concepts: **Organizations**, **Workspaces**, and **Teams**. ```mermaid theme={null} graph TD subgraph "Top-Level Organization" style Org fill:#e0f2fe,stroke:#0ea5e9 Org[Your Company Inc.] end subgraph "Workspace" style Ws fill:#f0f9ff,stroke:#0ea5e9 Ws[Primary Workspace
(Handles Billing & Users)] end subgraph "Teams" style T1 fill:#fafafa,stroke:#737373 style T2 fill:#fafafa,stroke:#737373 T1[Team: Network Operations] T2[Team: Security Auditors] end Org --> Ws; Ws --> T1; Ws --> T2; ``` ## Organizations: The Structural Foundation An **Organization** is the top-level entity that represents your entire business structure. It acts as a container for workspaces and allows you to create nested, hierarchical relationships up to 10 levels deep. This powerful feature enables: * **Modeling Complex Structures:** Mirror your company's real-world structure, such as global headquarters, regional divisions, and local departments. * **Resource Limit Enforcement:** Set resource caps (e.g., maximum number of sites) at any level. Limits are inherited downwards, and the most restrictive limit always applies, ensuring granular control over resource allocation. * **Usage Aggregation:** Resource consumption automatically rolls up the hierarchy, giving you a clear view of usage at every level, from a single team to the entire organization. ## Workspaces: The Billing and Tenancy Container A **Workspace** is the central hub for billing, user management, and multi-tenancy within an Organization. Each Workspace connects to a billing account and operates under one of three distinct **Billing Modes**, which is a permanent choice made at creation: **One billing account for everyone.** All teams and resources share a single, unified pool of subscriptions. Ideal for traditional companies with centralized billing. **Separate billing for each division.** Each top-level organization within your hierarchy has its own isolated billing account and resource pool. Perfect for MSPs or multinational corporations requiring strict separation. **Multiple contributors to a shared pool.** Several independent billing accounts contribute subscriptions to a common resource pool that all teams can draw from. Excellent for franchises or partner networks. ## Teams: The Unit of Collaboration A **Team** is the primary environment where your users collaborate and interact with network resources. All resources, such as sites, policies, and scripts, belong to a team. * **Scoped Access:** Users' permissions are determined by the roles they are assigned *within a specific team*. * **Resource Ownership:** Teams, not individual users, own resources. This ensures continuity and clear ownership. * **Multi-Team Membership:** A user can be a member of multiple teams, allowing them to switch contexts to manage different sets of resources. For detailed instructions on adding users, assigning roles, and managing team settings, see our User and Team Management guide. ## Common Use Cases Model your corporate structure by creating a root Organization for the company, with child Organizations for each department (e.g., "Engineering," "Sales"). Each department can then have its own teams. This allows you to set department-specific resource limits while aggregating total usage at the corporate level. Use **Assigned Mode**. Create a top-level Organization for each of your clients. This provides complete financial and operational isolation, ensuring one client cannot see or use the resources of another. You can manage all clients from a single login by being a member of each client's team. Use **Pooled Mode**. Each franchisee has their own independent billing account but contributes their purchased licenses to a shared pool. This allows a franchisee in one location to temporarily use an available license purchased by another, providing flexibility across the entire network while maintaining separate financial responsibility. # Generative AI Source: https://altostrat.io/docs/sdx/en/automation/generative-ai Meet your AI Co-pilot. Learn how to leverage our agentic AI to automate complex network tasks, from diagnostics to configuration, using natural language. Altostrat's Generative AI is more than just a chatbot; it's an **agentic AI Co-pilot** designed to be an active partner in managing your network. It can understand your goals, create a plan, and execute tasks by securely interacting with your MikroTik devices and the Altostrat platform on your behalf. This transforms network operations from a series of manual commands into a simple, conversational experience. ## What is an Agentic AI? Our AI operates on a "Think, Act, Observe" loop. Unlike traditional chatbots that only answer questions, our AI can use a suite of internal **Tools** to perform actions and gather live data to solve complex problems. ```mermaid theme={null} graph TD subgraph "Your Interaction" A[You: "Is my main office router healthy?"] end subgraph "AI Agent's Internal Loop" B{Think
"I need to find the 'main office' site ID and then check its health metrics."} --> C[Act: Use Tool
Calls the `getSites` tool to find the ID]; C --> D{Observe
Gets the Site ID from the tool's output}; D --> E{Think
"Now I have the ID. I'll use the `siteMetrics` tool to check its health."}; E --> F[Act: Use Tool
Calls the `siteMetrics` tool]; F --> G{Observe
Gets the uptime and status from the tool's output}; G --> H{Think
"The site is online with 99.9% uptime. I have enough information to answer."}; end subgraph "AI's Response" I[AI: "Yes, your main office router is healthy. It has been online with 99.9% uptime over the last 24 hours."] end A --> B; H --> I; ``` ## What Can the AI Co-pilot Do? The AI Co-pilot has access to a secure, read-only toolkit that allows it to interact with your network and our platform. The AI can list your sites, retrieve detailed hardware information (OEM), check performance metrics, and look up metadata or tags.
**Ask it:** *"How many sites do I have in the APAC region?"* The AI can execute real-time, read-only commands on your MikroTik devices, such as running a ping or traceroute, or printing the current routing table.
**Ask it:** *"From my London router, can you ping 8.8.8.8?"* The AI can retrieve and analyze configuration backups. It can compare configurations between two sites or identify specific rules within a backup file.
**Ask it:** *"Compare the firewall rules between my New York and London sites."* The AI has access to the full Altostrat documentation. It can explain features, provide best practices, and guide you on how to use the platform.
**Ask it:** *"How do I set up a Captive Portal with coupon authentication?"* ## Best Practices for Interacting with the AI To get the best results from your AI Co-pilot, follow these prompting guidelines: Provide as much context as you can. Instead of "Check my router," say "What is the uptime for my 'Main Office' router over the last 24 hours?" Tell the AI what you are trying to achieve. Instead of "Show me the firewall rules," say "I'm trying to figure out why I can't access my web server. Can you check the firewall rules on the 'Web Server' site?" The AI is a powerful assistant, but you are the pilot. For any configuration changes it suggests, review them carefully before applying them. Use its output as expert guidance, not blind instruction. For deploying changes at scale, use [Script Management](/sdx/en/automation/script-management). # Automation & AI Overview Source: https://altostrat.io/docs/sdx/en/automation/introduction An overview of Altostrat's automation suite. Learn how to orchestrate tasks with the visual Workflow engine, deploy changes with Script Management, and leverage our agentic AI Co-pilot. Stop fighting fires and start building automations. The Altostrat SDX platform is designed to move your team from repetitive, manual tasks to intelligent, event-driven orchestration. Our comprehensive automation and AI suite provides a set of powerful, complementary tools to help you manage your network at scale, reduce human error, and reclaim your time. Whether you're building a complex, multi-step integration, deploying a critical configuration change across your fleet, or diagnosing an issue with natural language, our platform has the right tool for the job. ## The Three Pillars of Automation Our automation philosophy is built on three distinct engines, each tailored for a different approach to getting work done. The visual automation engine. Connect triggers, actions, and conditions to build powerful, event-driven processes. Perfect for API integrations, notifications, and "if-this-then-that" logic without writing code. The power of RouterOS, delivered at scale. Centrally manage, test, and schedule the execution of your custom RouterOS scripts across your entire fleet with built-in safety features like authorization workflows. The conversational automation layer. Use natural language to ask your AI Co-pilot to diagnose issues, analyze configurations, generate scripts, and execute complex tasks on your behalf. ```mermaid theme={null} graph TD subgraph "Your Intent" A[API Event] B[Scheduled Time] C[Natural Language Prompt] end subgraph "Altostrat Automation Engine" W[Workflow Engine] S[Script Engine] AI[AI Co-pilot] end subgraph "Automated Actions" F[Execute on MikroTik Fleet] G[Call External API] H[Generate Report] end A & B --> W; C --> AI; AI -- "Can orchestrate" --> W & S; W --> G & H; S --> F; ``` ## In This Section Dive deeper into the components of our automation and AI suite. Learn about all the ways you can start a workflow, from a recurring schedule to a real-time API call. Discover the powerful nodes for performing tasks and making decisions in your visual automations. A guide to securely storing and using API keys, tokens, and other sensitive credentials in your workflows. Master the lifecycle of RouterOS script automation, from creation and testing to scheduling and deployment. Learn how to interact with your agentic AI to diagnose issues, analyze configurations, and automate tasks. # Script Management & Orchestration Source: https://altostrat.io/docs/sdx/en/automation/script-management Centrally manage, test, authorize, and execute MikroTik RouterOS scripts across your fleet with built-in safety checks, reusable templates, and AI-powered generation. Altostrat's Script Management transforms how you deploy changes and run operational tasks on your MikroTik fleet. Instead of manually connecting to each device, you can write, schedule, and monitor script executions from a single, centralized platform. This provides a scalable, auditable, and safe way to automate everything from routine maintenance to fleet-wide configuration updates, leveraging the platform's asynchronous job engine for reliable delivery. ## How it Works: The Asynchronous Job Lifecycle When you schedule a script, you create a **Scheduled Script** job within the SDX platform. This job progresses through a series of states, and its payload is delivered to target devices via our secure, poll-based communication model. This ensures commands are delivered reliably, even to devices on unstable connections. You create a script and define its targets. The job begins in an `unauthorized` state. An approver must then authorize it, moving it to `scheduled`. This two-step process provides a critical control gate for all network changes. At the scheduled `launch_at` time, the job's status changes to `launched`. For each target site, a unique **Outcome** record is created to track its individual progress. When a target device next checks in with the Altostrat platform, it receives the script, reports its status as `busy`, executes the payload, and finally reports back with a `completed` or `failed` status. This entire process is logged for auditing. ```mermaid theme={null} stateDiagram-v2 direction LR [*] --> Unauthorized: Create Scheduled Script Unauthorized --> Scheduled: Admin clicks 'Request Authorization' & Approver approves Unauthorized --> Canceled: Admin deletes job Scheduled --> Launched: launch_at time is reached Scheduled --> Canceled: Admin cancels job state "Execution on Each Device" as Execution { Launched --> In_Progress: Device polls and receives job In_Progress --> Completed: Script finishes successfully In_Progress --> Failed: Script encounters an error } ``` This asynchronous process is fundamental to the platform's security and resilience. Because the device initiates the connection to fetch the job, you never need to open inbound firewall ports. ## The Script Management Toolset Our platform provides a complete ecosystem for the entire script lifecycle, from creation to execution. The core execution engine. Define a RouterOS script, select your target sites, and schedule it to run. Includes built-in safety features like pre-flight backups and a mandatory authorization workflow. Build a library of reusable, standardized scripts. Templates can be private to your organization or designated as **Global** (read-only and available to all users), enforcing consistency and best practices. Don't reinvent the wheel. Browse and import from a curated library of public scripts for common MikroTik tasks, sourced directly from the community on GitHub. Your expert co-pilot. Describe your intent in plain English (e.g., "Block all traffic from this IP address"), and our AI will generate a functional and safe RouterOS script for you. ## The Scripting Workflow: A Focus on Safety Our workflow is designed with safety and control as top priorities, ensuring changes are tested, approved, and auditable. 1. Navigate to **Automation → Script Management** and click **Create Scheduled Script**. 2. **Configuration:** * **Description:** Give the job a clear, auditable name (e.g., "Q4-2025: Nightly Guest WiFi Disable"). * **Script Content:** Write your RouterOS script, or load it from a **Template**. * **Targets:** Select the **Site(s)** where the script will run. * **Schedule:** Set the **Launch At** time for the execution. 3. **Safety Options:** * **Make Backup:** **(Highly Recommended)** If enabled, the platform automatically prepends a command to your script that performs a secure configuration backup via SFTP *before* your script content is executed. This creates an immediate rollback point for every device. * **Test Site:** Designate one of your target sites as a test site. This allows you to run a one-off test before scheduling the full deployment. 4. Click **Save**. The script is now in an `unauthorized` state. Before deploying to your entire fleet, validate the script's behavior on your designated test site. 1. Find your newly created script in the list. 2. Click the **Run Test** button. 3. A test job is dispatched immediately *only* to the test site. Monitor the **Orchestration Log** for that site to verify the outcome and check for any errors. For security and compliance, a scheduled script must be explicitly authorized before it can run. This creates a clear, auditable approval record for all network changes. 1. Once you are confident in your script, click the **Request Authorization** button. 2. This triggers a notification (via Email and WhatsApp) to the designated approvers in your team, containing a unique, secure link to approve the script's execution. 3. An authorized user reviews the script details and approves it, moving its status to `Scheduled`. At the scheduled `launch_at` time, the job begins. You can monitor its progress in real-time from the Script Management dashboard, which shows the status of each target site: `pending`, `completed`, or `failed`. For detailed output from a specific device, consult its **Orchestration Log**. ## AI Script Generation Leverage our generative AI to accelerate your scripting process and translate your operational intent into RouterOS code. 1. From the script editor, click on the **AI Generate** tab. 2. In the prompt box, write a clear, concise description of the task you want to accomplish. For best results, state your goal and provide context (e.g., "I need to create a firewall rule to block access to our internal server at 10.1.1.5 from the guest VLAN"). 3. Click **Generate**. The AI will produce a script based on your request. **Always review AI-generated scripts carefully.** The AI analyzes the script and will flag it as potentially **destructive** if it contains commands that could cause a loss of connectivity or delete data. Treat these scripts as an expert-drafted starting point, not as a blind instruction. Always use the **Run Test** feature to validate their behavior in a controlled environment before deploying. ## Best Practices Always use the **Run Test** feature on a non-critical site. This is the single most important step to prevent unintended consequences across your fleet. Write scripts that are self-contained and can be run multiple times without causing errors. For example, use `find` commands to check if a rule already exists before trying to add it, preventing duplicate configurations. For any script you plan to reuse, save it as a **Template**. This enforces consistency, saves your team time, and reduces the risk of copy-paste errors. Standardize common tasks by creating shared, read-only **Global Templates**. # Building Workflows: Actions and Conditions Source: https://altostrat.io/docs/sdx/en/automation/workflows/building-workflows A complete guide to the building blocks of automation. Learn how to use actions to perform tasks and conditions to create intelligent, branching logic. Once a workflow is started by a [Trigger](/sdx/en/automation/workflows/triggers-and-webhooks), its real power comes from the sequence of **Actions** and **Conditions** that follow. These are the nodes you use to build out your automation's logic, allowing you to perform tasks, make decisions, and manipulate data. * **Actions** are the workers; they *do* things. * **Conditions** are the brains; they *decide* things. By connecting these nodes, you create a visual flowchart that represents your automated process. ```mermaid theme={null} graph TD A[Trigger] --> B{Condition}; B -- True --> C[Action 1]; B -- False --> D[Action 2]; C --> E((End)); D --> E((End)); ``` ## Actions: Performing Tasks Actions are nodes that perform a specific task, such as calling an external API, pausing the workflow, or transforming data. We can group them into three main categories: These actions allow your workflow to communicate with the outside world. * **Webhook:** Send HTTP requests (`GET`, `POST`, etc.) to any third-party API. * **Altostrat API:** Make authenticated calls to the Altostrat platform API itself. These actions control the execution path and timing of your workflow. * **Delay:** Pause the workflow for a specified duration (e.g., 5 minutes). * **Iterator:** Loop over an array of items and run a sub-workflow for each one. * **Trigger Workflow:** Call another, separate workflow, enabling modular design. * **Terminate:** Stop the workflow immediately with a `completed` or `failed` status. These actions are used to reshape, parse, and generate data within your workflow. * **Data Mapper:** Create new JSON objects by mapping values from previous steps. * **JSON Parser:** Convert a JSON string into a structured object. * **Text Transform:** Generate dynamic text using powerful Liquid templating. * **Date Transform:** Perform calculations and formatting on date/time values. ## Conditions: Making Decisions Conditions are decision-making nodes that evaluate data and create branching paths. Each condition node typically has at least two outputs: `true` and `false`, allowing you to route the workflow based on the result. Compare text values. Use this to check status fields, user input, or any other text-based data. *(Operators: `equals`, `contains`, `starts_with`, `regex`, etc.)* Evaluate numeric values. Perfect for checking amounts, counts, or scores. *(Operators: `greater_than`, `less_than_or_equal`, etc.)* Perform time-based logic. Check if a date is in the past, future, or within a certain range. *(Operators: `is_past`, `is_within`, `is_after`, etc.)* Check for `true` or `false` values. Ideal for evaluating flags or binary states from API responses. *(Operators: `is_true`, `is_false`)* Evaluate lists of items. Check if an array is empty, contains a specific value, or matches a count. *(Operators: `is_empty`, `count_greater_than`, `contains_value`, etc.)* Build complex decision trees. The **Logical Group** combines multiple rules with AND/OR logic, while the **Switch** provides multi-path routing based on the first matching case. ## Connecting Nodes You build a workflow by drawing **edges** (lines) between the **handles** (dots) on each node. Most action nodes have a single output handle, while condition nodes have multiple handles (`true`, `false`, `error`) to direct the flow. ```mermaid theme={null} graph TD A[Action 1] --> B{Condition}; B -- "handle: true" --> C[Action for True]; B -- "handle: false" --> D[Action for False]; ``` ## Passing Data Between Nodes with Liquid The real power of workflows comes from passing data between steps. You can reference the output of any previous node using **Liquid templating**. The syntax is simple: `{{ node_id.output_key }}`. For example, if a Webhook Trigger (`node_1`) receives a payload like `{"user": {"id": 123, "name": "Alice"}}`, a later Text Transform node could create a personalized message: `Hello, {{ node_1.body.user.name }}!` which would render as `Hello, Alice!`. Liquid is essential for dynamic workflows. Dive into our dedicated guide to learn about objects, tags (`if/for`), and filters (`upcase`, `date`, etc.). ## Next Steps Revisit the complete guide to all the ways you can start a workflow. Learn how to securely store and use API keys, tokens, and other secrets in your actions. # Workflow Triggers and Webhooks Source: https://altostrat.io/docs/sdx/en/automation/workflows/triggers-and-webhooks Learn how to start your automations with a complete guide to all available workflow triggers, including schedules, webhooks, manual execution, and platform events. A Workflow Trigger is the event that initiates an automation. Every workflow must have exactly one trigger, which acts as its designated starting point. Choosing the right trigger is the first step in building any workflow, as it defines *when* and *how* your process will run. ```mermaid theme={null} graph LR subgraph "Events" A[Schedule
(e.g., Every Hour)] B[Webhook Call
(HTTP POST)] C[Manual Action
(User clicks 'Run')] end subgraph "Workflow Engine" D{Trigger Node} end subgraph "Automation" E[Workflow Executes...] end A --> D B --> D C --> D D --> E ``` ### Webhook Trigger vs. Webhook Action It's important to understand the difference between a Webhook *Trigger* and a Webhook *Action*, as they serve opposite purposes. A Webhook Trigger **starts a workflow from an external event**. It provides a unique URL that waits for an incoming HTTP POST request from a third-party service. When the request is received, the workflow begins, and the request's body and headers become the initial data. A Webhook Action **sends an HTTP request to an external service *during* a workflow**. It is a step within your automation used to call a third-party API, send a notification, or push data to another system. ## Available Trigger Types ### Scheduled Trigger Use a Scheduled Trigger to run workflows automatically on a recurring basis. This is perfect for maintenance tasks, generating reports, or syncing data periodically. **Common Use Cases:** * Run a daily health check on all sites. * Generate and email a weekly performance report. * Sync data with an external system every 15 minutes. #### Configuration The type of recurrence for the schedule. * **`interval`**: Runs at a fixed interval. Requires a `schedule_value` like `"5 minutes"` or `"2 hours"`. * **`cron`**: Runs based on a standard cron expression. Requires a `schedule_value` like `"0 9 * * 1"` (Every Monday at 9:00 AM). * **`daily`**: A simplified option to run the workflow once per day at a specific time. * **`weekly`**: Runs the workflow on a specific day of the week at a specific time. * **`monthly`**: Runs the workflow on a specific day of the month at a specific time. ### Webhook Trigger Use a Webhook Trigger to start a workflow from an external system in real-time. This trigger provides a secure, unique URL to receive HTTP POST requests. **Common Use Cases:** * Process a payment confirmation from a service like Stripe. * Handle a new form submission from a website. * Respond to an alert from a third-party monitoring system. #### Configuration This trigger has no user-configurable options. The secure URL is automatically generated when you save the workflow. #### Output The output of the Webhook Trigger node will be a JSON object containing the `body` and `headers` of the incoming HTTP request, which can be used in subsequent steps. ### Manual Trigger Use a Manual Trigger for workflows that require on-demand execution by a user from the SDX dashboard. **Common Use Cases:** * Run a one-time diagnostic script on a specific site. * Manually provision a new user or resource. * Execute an emergency "lockdown" procedure. #### Configuration You can define a JSON schema for the input data. When a user runs the workflow, the UI will generate a form based on this schema, ensuring they provide the correct data. ### SNS Trigger (Advanced) Use an SNS Trigger to start a workflow in response to internal Altostrat platform events. This allows for deep, event-driven integration with the platform's lifecycle. **Common Use Cases:** * When a new site is created, automatically apply a set of default tags. * When a `WAN Failover` event occurs, create a ticket in an external system. * When a user is added to your team, send them a welcome message. #### Configuration The specific platform event pattern to listen for. Wildcards (`*`) are supported. For example, `site.created` or `fault.*`. You can listen for multiple events (e.g., `site.created,site.updated`), but they must belong to the same root category. ### Workflow Trigger Use a Workflow Trigger to create modular, reusable "sub-workflows" that can be called by other workflows. This is essential for building complex, maintainable automations. **Common Use Cases:** * A reusable "Send Slack Notification" workflow that can be called by dozens of other workflows. * A common "Error Handling" workflow that logs details to a specific service. * A "User Validation" workflow that checks user data and returns a standardized result. A workflow with this trigger cannot be started on its own via a schedule or webhook. It can **only** be triggered by another workflow using a **Trigger Workflow Action**. #### Configuration Define the data structure you expect to receive from the calling workflow. This is for documentation and helps validate the incoming payload. ## Next Steps Now that you've chosen a trigger, the next step is to build out the logic of your automation. Discover the actions and conditions you can use to create powerful, branching logic. Learn how to securely store and use API keys, tokens, and other secrets in your workflows. # Using the Vault for Secrets Source: https://altostrat.io/docs/sdx/en/automation/workflows/using-the-vault Learn how to securely store, manage, and use sensitive credentials like API keys and tokens in your workflows with the Altostrat Vault. Hardcoding sensitive information like API keys, authentication tokens, or passwords directly into your workflows is insecure and makes managing credentials difficult. The **Altostrat Vault** solves this problem by providing a secure, centralized location to store your secrets. Values stored in the Vault are encrypted at rest and can **only** be accessed by your workflows during execution. The secret values are never exposed in the UI or API responses after they are created, ensuring your credentials remain confidential. ## The Secure Workflow with the Vault ```mermaid theme={null} graph TD subgraph "Setup Phase (You)" A[User adds an API key to the Vault] --> V[Vault
(Encrypted Storage)]; end subgraph "Execution Phase (Automated)" W[Workflow Run] -- "1. Reads secret reference
e.g., '{{ vault.my_api_key }}'" --> V; V -- "2. Securely injects
the secret value" --> W; W -- "3. Uses the secret in an action" --> WA[Webhook Action]; WA -- "4. Makes authenticated call" --> E[External API]; end ``` ## Managing Secrets in the Vault In the SDX dashboard, go to **Automation → Vault**. This will display a list of all the secrets you have stored. Note that only the names and metadata are shown, never the secret values themselves. Click **+ Add Item** to create a new secret. 1. **Name:** Provide a unique, descriptive name for your secret. This is how you will reference it in your workflows (e.g., `stripe_production_key`). 2. **Secret Value:** Paste the sensitive value (the API key, token, etc.) into this field. This is the only time you will enter the secret. 3. **Expiration (Optional):** Set an optional expiration date for the secret. This is a good security practice for rotating keys. 4. Click **Save**. From the Vault list, you can click on any item to update its name or secret value, or click the trash can icon to permanently delete it. ## Using a Secret in a Workflow Once a secret is stored in the Vault, you can reference it in any workflow action that supports text input (like a Webhook action's headers or body). To reference a secret, use the `vault` object with Liquid syntax: `{{ vault.your_secret_name }}` ### Example: Authenticating an API Call The most common use case is providing a bearer token in an `Authorization` header for a Webhook action. 1. Create a Webhook action in your workflow. 2. Add a new header with the key `Authorization`. 3. For the value, enter your secret reference. If the secret name is `my_service_api_key`, the value would be: `Bearer {{ vault.my_service_api_key }}` During execution, the workflow will replace the Liquid tag with the actual secret value from the Vault before sending the request. ## Special Feature: Generating API Keys The Vault can also generate secure, random API keys for you. This is useful when you need to provide a key to an external service so it can securely call one of your **Webhook Triggers**. To generate a key, simply prefix the **Name** with `api-key:` when creating a new Vault item. For example, `api-key:incoming-webhook-key`. Leave the **Secret Value** field blank, and the system will generate a secure key for you and display it *once*. ## Best Practices The most important rule. Always use the Vault for API keys, tokens, passwords, and any other sensitive string. This is the primary purpose of the Vault. Name your secrets clearly, including the environment if applicable (e.g., `stripe_test_key`, `slack_webhook_production`). This makes your workflows easier to read and manage. For high-security credentials, set an expiration date when you create them in the Vault. This encourages good security hygiene by prompting you to rotate keys periodically. # Configuring a Captive Portal Source: https://altostrat.io/docs/sdx/en/connectivity/captive-portals/configuration A step-by-step guide to creating and customizing your captive portal, including setting up Auth Integrations (IDPs), choosing a strategy, and applying it to a site. This guide provides the practical steps for setting up a new Captive Portal, from configuring authentication methods to applying it to your live network. ## Part 1: Configure an Auth Integration (OAuth2 Only) If you plan to use an OAuth2 strategy (e.g., "Login with Google"), you must first configure the Identity Provider (IDP) as a reusable **Auth Integration**. If you are only using the Coupon strategy, you can skip to Part 2. In the SDX dashboard, navigate to **Connectivity → Captive Portal** and select the **Auth Integrations** tab. Click **+ Add**. 1. Give the integration a descriptive **Name** (e.g., "Corporate Azure AD"). 2. Select the **Type** (Google, Azure, or GitHub). 3. Enter the credentials obtained from your identity provider's developer console: The public identifier for your application. The secret key for your application. This is sensitive information. Required only for Azure AD, specifying your organization's directory. When creating your application in the IDP's console (e.g., Google Cloud, Azure Portal), you **must** add `https://auth.altostrat.app/callback` as an **Authorized Redirect URI**. This is a critical step for the authentication flow to work. Click **Save**. A **Test URL** will be generated. Use this to verify that the authentication flow is working correctly *before* applying it to a live portal. ## Part 2: Create and Configure the Portal Instance This is the main workflow for creating and customizing your guest network's login page. Navigate to the **Instances** tab and click **+ Add**. 1. **Name:** Provide a name for your portal (e.g., "Main Office Guest WiFi"). 2. **Authentication Strategy:** Choose `OAuth2` or `Coupon`. 3. **Session TTL:** Set the duration a user's session remains active after they log in. This can range from 20 minutes (`1200` seconds) to 7 days (`604800` seconds). 4. **Auth Integration:** If you chose `OAuth2`, select the integration you configured in Part 1. 5. Click **Create**. Once the instance is created, click on it to open the editor. Upload a **Logo** and a browser **Icon** (favicon) to represent your brand on the login page. Customize the look and feel of your portal. All color values must be in hex format (e.g., `#0396d5`). * **Accent Text:** Color for text on buttons. * **Accent Color:** Primary color for buttons and links. * **Text Color:** Main text color. * **Secondary Text Color:** Lighter text for subtitles. * **Background Color:** Page background. * **Box Color:** Background of the main login container. * **Border Color:** Color for input fields and container borders. Enter the terms and conditions that users must agree to before connecting. You can use Markdown for basic formatting. Leave this blank to disable the terms of service checkbox. The final step is to activate the portal on your network. 1. In the instance editor, go to the **Sites** tab. 2. Click **Add Site**. 3. Select the **Site** where you want to enable the portal. 4. Specify the **Subnet(s)** on that site's network that should be managed by the portal (e.g., your guest VLAN's subnet, like `192.168.88.0/24`). 5. Click **Save**. Altostrat will now orchestrate the necessary firewall and redirect rules on your MikroTik device. New users connecting to the specified subnet will be automatically redirected to your captive portal. ## Part 3: Managing Coupon Authentication If you chose the **Coupon** strategy for your instance, you can generate access codes in two ways.
### On-Demand Coupons For immediate, manual distribution. 1. Navigate to your coupon-based instance. 2. Go to the **Coupons** tab and click **Generate Coupons**. 3. Specify the **Count** (how many to create, max 200 at a time) and how long they should be **Valid For**. 4. The generated codes will be displayed and can be distributed to guests.
### Scheduled Coupon Generation For automated, recurring generation. 1. Navigate to your instance and go to the **Coupon Schedules** tab. 2. Click **Add Schedule**. 3. Configure the schedule to automatically generate a batch of coupons on a `Daily`, `Weekly`, or `Monthly` basis (e.g., "Generate 50 new 8-hour coupons every day at 8 AM"). 4. Select a **Notification Group** to receive an email with a link to the generated coupons.
## Part 4: Monitoring and User Management From the main site overview page, navigate to the **Captive Portal Users** tab to see a list of all users who are currently active or have previously connected through the portal at that site. From here, you can: * View session details like IP address, MAC address, and session expiration. * Manually disconnect an active user session if needed. # Introduction to Captive Portals Source: https://altostrat.io/docs/sdx/en/connectivity/captive-portals/introduction Understand how to create branded, secure guest Wi-Fi experiences with Altostrat's Captive Portal service, using OAuth2 or coupon-based authentication. Altostrat's Captive Portal service allows you to provide secure, controlled, and branded internet access for guests on your network. When a user connects to a designated guest Wi-Fi or LAN segment, their traffic is intercepted and they are redirected to a customizable login page. They must authenticate before gaining full internet access. This is ideal for corporate guest networks, retail locations, hotels, and any environment where you need to manage and track guest access. ## How It Works: The Connection Flow The magic of the captive portal happens through a seamless, automated redirection process. When a guest's device tries to access the internet, your MikroTik router intelligently intercepts the request and guides them through authentication. ```mermaid theme={null} graph TD subgraph "Guest's Device" A[1\. Connects to Wi-Fi
Tries to access a website] end subgraph "Your MikroTik Router" B{2\. Intercepts DNS/HTTP Traffic}; B --> C[3\. Redirects to Altostrat STUN Service]; end subgraph "Altostrat Cloud" STUN[4\. STUN Service
Captures user's internal & external IPs]; PORTAL[6\. Captive Portal Page
User Authenticates]; AUTH[7\. Auth Service]; end subgraph "Your MikroTik Router" AUTH_ROUTER{9\. Authorizes Session
Adds user's IP to 'allow' list}; end subgraph "Internet" FINAL((10\. Full Internet Access Granted)); end A --> B; C --> STUN; STUN -- "5\. Creates Secure Token & Redirects" --> PORTAL; PORTAL -- "OAuth2 or Coupon" --> AUTH; AUTH -- "8\. Sends 'Authorize' command to SDX" --> AUTH_ROUTER AUTH_ROUTER --> FINAL ``` 1. **Connection:** A guest connects to your designated Wi-Fi network. 2. **Interception:** The on-site MikroTik router, configured by SDX, intercepts the user's first attempt to access an external website. 3. **STUN Redirect:** The router redirects the user to our **STUN (Session Traversal Utilities for NAT)** service. This lightweight service is critical for identifying the user's internal IP address even when they are behind NAT. 4. **Secure Token:** The STUN service captures the user's internal and external IP addresses, along with the Site ID, encrypts this data into a secure, short-lived token, and redirects the user to the main Captive Portal page with this token. 5. **Authentication:** The user sees your branded login page and authenticates using one of the strategies you've configured. 6. **Authorization:** Upon successful authentication, the Altostrat platform sends a secure command to your MikroTik router, instructing it to add the user's internal IP address to a temporary "allow" list in its firewall for a specified duration (`Session TTL`). 7. **Access Granted:** The user now has full internet access until their session expires. ## Core Concepts The complete configuration for a single captive portal, including its name, branding (theme), authentication strategy, and session rules. You can have multiple instances for different locations or networks. A reusable configuration for a third-party Identity Provider (e.g., Google, Microsoft Azure, GitHub). This is required if you use the OAuth2 authentication strategy. A crucial list of IP addresses and domains that guests are allowed to access *before* they authenticate. This is essential for allowing users to reach the login pages of identity providers like Google or Microsoft. ## Authentication Strategies Altostrat offers two flexible authentication strategies for your captive portals. Allow users to authenticate using their existing Google, Microsoft Azure, or GitHub accounts. This provides a seamless login experience and captures the user's name and email for tracking and accountability. Generate unique, single-use access codes (coupons) that you can distribute to guests. This method is perfect for environments like hotels or conference centers where you want to provide temporary, controlled access without requiring users to have a specific online account. ## Next Steps Learn the practical steps to set up an Auth Integration, create your first portal instance, customize its branding, and apply it to a site. # Connectivity & SD-WAN Source: https://altostrat.io/docs/sdx/en/connectivity/introduction An overview of Altostrat's cloud-managed tools for building resilient, secure, and flexible network fabrics, including WAN Failover, Managed VPN, and Captive Portals. Connectivity is more than just an internet link; it's the lifeblood of your business. Altostrat SDX provides a suite of powerful, cloud-managed tools designed to transform basic internet connections into a resilient, secure, and flexible network fabric. Whether you need to ensure 100% uptime with multiple WANs, securely connect your branch offices and remote users, or provide controlled internet access for guests, our platform gives you the building blocks to orchestrate connectivity with confidence. ```mermaid theme={null} graph TD subgraph "Your Altostrat-Managed Router" A[MikroTik Device] end subgraph "Resilience (WAN Failover)" A -- "Primary Link" --> B((Internet)); A -- "Backup Link" --> C((Internet)); end subgraph "Secure Access (Managed VPN)" A --> D[Cloud VPN Hub]; D --> E[Remote Site]; D --> F[Remote User]; end subgraph "Controlled Access (Captive Portal)" G[Guest User] --> A; A -- "Intercepts & Authenticates" --> H((Internet)); end ``` ## Core Connectivity Services Achieve maximum uptime by combining multiple internet connections. Our platform automatically detects ISP outages and reroutes traffic to a working link in seconds, ensuring your business stays online. Build a secure, private network fabric in minutes. Effortlessly create site-to-site tunnels to connect your offices and provide secure remote access for your team, all orchestrated from the cloud. Deliver a professional and secure guest Wi-Fi experience. Create branded login pages that authenticate users via social logins (OAuth2) or time-limited access coupons. ## In This Section Dive into the detailed guides for each of our connectivity services. A step-by-step guide to configuring and managing a multi-WAN setup for high availability. Learn the core concepts of our cloud-hosted VPN service, including Instances and Peers. Follow the practical steps to create VPN instances and add site and client peers. Understand the authentication strategies and core concepts behind our guest portal service. A step-by-step guide to setting up and customizing your guest Wi-Fi login experience. # Configuring a Managed VPN Source: https://altostrat.io/docs/sdx/en/connectivity/managed-vpn/instances-and-peers A step-by-step guide to creating a VPN Instance, configuring advanced settings, adding Site Peers for site-to-site connectivity, and adding Client Peers for secure remote user access. This guide provides the practical steps for setting up and managing your secure network fabric using Altostrat's Managed VPN. The process involves creating a central cloud hub (an Instance) and then connecting your sites and users to it as Peers. ## Part 1: Creating Your First VPN Instance The first step is to provision your cloud hub. In the SDX Dashboard, select **Connectivity** from the main menu, then click on **Managed VPN**. Click **Create Instance**. You will be asked to provide the following details: * **Name:** A descriptive name for your VPN (e.g., "Production Corporate VPN"). * **Hostname:** A unique hostname that will form part of your VPN's public address (e.g., `my-company-vpn`). This will be accessible at `my-company-vpn.vpn.altostr.at`. * **Region:** Select the geographical region closest to the majority of your users and sites. Choosing the closest region to your peers is the most important factor for minimizing latency and ensuring the best performance. Click **Create** to begin the provisioning process. This may take a few minutes as we deploy a dedicated server for your instance. ## Part 2: Configuring Instance Settings Once the instance is active, you can click on it to configure advanced network and DNS settings that will be pushed to all connecting peers. In the **Pushed Routes** section, you can define additional IP prefixes that all connected peers should route through the VPN. This is useful for providing access to networks that are not directly advertised by a Site Peer, such as a cloud VPC. By default, this includes standard RFC1918 private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`). The Managed VPN Instance acts as a DNS server for connected peers. You can customize its behavior: * **Public DNS:** The upstream DNS resolvers the instance will use for public queries (defaults to Quad9). * **Split DNS & Domains:** Define specific domains that should be resolved by the instance's private DNS. All other queries will go to the public resolvers. This is ideal for resolving internal hostnames. * **Custom DNS Records:** Create custom `A` or `CNAME` records for your private network (e.g., mapping `intranet.corp` to `10.1.1.5`). ## Part 3: Adding Peers With your instance running, you can now connect your sites and users to it. **Billing:** Each peer (whether a Site Peer or Client Peer) consumes one seat. For example, if you connect 2 sites and 3 users, you will be billed for 5 seats total. ### Adding a Site Peer (Site-to-Site VPN) Connect one of your SDX-managed MikroTik routers to the VPN to make its local network accessible. 1. Navigate to your VPN Instance and open the **Peers** tab. 2. Click **Add Peer** and select the type **Site**. 3. From the dropdown, choose the SDX-managed **Site** you wish to connect. 4. Select the **Protocol** for the tunnel (`WireGuard` or `OpenVPN`). WireGuard is recommended for higher performance. 5. Select the **Subnets** from that site's local network that you want to make accessible ("advertise") over the VPN. 6. Click **Add**. Altostrat will automatically orchestrate the creation of the VPN tunnel on your MikroTik device. Within minutes, its status will show as connected, and its advertised subnets will be reachable by other peers. ### Adding a Client Peer (Remote User VPN) Create a secure connection profile for a remote user. This process uses the modern and secure WireGuard protocol. 1. Navigate to your VPN Instance and open the **Peers** tab. 2. Click **Add Peer** and select the type **Client**. 3. From the dropdown, select the **User** this peer will be assigned to. 4. Configure the tunneling behavior: **Route All Traffic: Disabled**
Only traffic destined for private subnets will go through the VPN. This is best for performance and conserves bandwidth. **Route All Traffic: Enabled**
All of the user's internet traffic will be sent through the VPN. This is best for maximum security and traffic inspection. 5. Click **Add**. A new client peer will be created. 6. Click the **Get Config** button next to the peer to download the WireGuard configuration file (`.conf`) or display a **QR code**. The user can import this file or scan the QR code with their WireGuard client on their laptop or mobile device to connect. ## Part 4: Monitoring Your VPN From the instance overview page, you can monitor the health and activity of your VPN: * **Peer Status:** The **Peers** tab shows a real-time list of all configured peers, their assigned VPN IP addresses, their public source IP, and their current connection status (`online`/`offline`). * **Bandwidth Usage:** The **Statistics** tab provides graphs of bandwidth usage for the entire instance, helping you monitor traffic patterns and plan for capacity. ## Best Practices Deploy your instance in the region that is geographically closest to the majority of your peers. This is the single most important factor for minimizing latency. When adding a Site Peer, only advertise the specific subnets that need to be accessible. Avoid advertising your entire LAN unless necessary to prevent route conflicts and keep the routing table clean. For most remote user cases, a split tunnel provides the best balance of security and performance, only routing internal traffic through the VPN and letting general internet traffic go direct. # Introduction to Managed VPN Source: https://altostrat.io/docs/sdx/en/connectivity/managed-vpn/introduction Understand the core concepts of Altostrat's Managed VPN service, including Instances and Peers, for building secure site-to-site and remote user networks. Altostrat's Managed VPN is a turnkey cloud service that simplifies the creation of secure, private networks. It eliminates the complexity of manually configuring and maintaining traditional IPsec or WireGuard tunnels, allowing you to build a robust connectivity fabric for your sites and remote users in minutes. The service orchestrates a secure **hub-and-spoke topology**, where a central, cloud-hosted gateway (**Instance**) provides private connectivity for your distributed MikroTik routers and remote workers (**Peers**). ```mermaid theme={null} flowchart TD subgraph "Altostrat Cloud (Your Private Hub)" A["VPN Instance
(Cloud Concentrator)"] end subgraph "Your Network" B["Site Peer
(MikroTik Router in Office)
OpenVPN or WireGuard"] C["Client Peer
(Remote User's Laptop)
WireGuard"] end B -- "Secure Tunnel" --> A C -- "Secure Tunnel" --> A B <-.-> C ``` ## Core Concepts Our Managed VPN is built on two fundamental components: Instances and Peers. An **Instance** is your private, cloud-hosted VPN concentrator or server. You deploy an instance in a specific geographical region to ensure low latency for your connected peers. The instance acts as the central hub of your VPN, controlling network settings, routing, and DNS for all connected peers. A **Peer** is any device that connects to your VPN Instance. There are two types: * **Site Peers:** Your SDX-managed MikroTik routers, connecting via OpenVPN or WireGuard. Connecting a site peer makes its local subnets securely accessible to other peers. * **Client Peers:** Individual remote user devices (laptops, phones), connecting via WireGuard. This allows your team to securely access network resources from anywhere. ## Primary Use Cases The Managed VPN service is designed to solve two primary connectivity challenges: Securely connect your branch offices, data centers, and other physical locations. Once two sites are connected as peers to the same instance, they can communicate with each other's private subnets through the secure cloud hub, creating a seamless private network over the public internet. Provide your team with secure, one-click access to internal network resources. Instead of exposing services to the internet, users connect to the VPN instance and can access internal servers, file shares, and applications as if they were in the office. ## How It Connects to Your Bill Altostrat's Managed VPN is integrated with your workspace's subscription plan. Each **Peer** you create (whether a Site Peer or Client Peer) consumes one seat from your available resource pool. * **Initial Capacity:** Each VPN Instance you create includes a base capacity of **10 seats** at no additional cost. * **Scaling Up:** If you add more than 10 Peers to an instance, each additional peer will consume one seat from your subscription. * **Billing Example:** Connecting 2 sites and 3 users to an instance will consume 5 seats total. For a complete overview of how resource metering and subscriptions work, please see our main Billing and Subscriptions guide. ## Next Steps Now that you understand the core concepts, you're ready to build your first secure network. Learn the practical steps to create your first VPN instance, add site and client peers, and manage your secure network. # WAN Failover Source: https://altostrat.io/docs/sdx/en/connectivity/wan-failover Configure multiple internet connections on your MikroTik router to ensure continuous, uninterrupted network connectivity. # WAN Failover WAN Failover is a critical SD-WAN feature that ensures network resilience and business continuity. It allows you to combine multiple internet connections (e.g., Fiber, LTE, Starlink) on a single MikroTik device. Altostrat SDX continuously monitors the health of each link and, if your primary connection fails, automatically reroutes all traffic through a working secondary link in seconds. This process is seamless and ensures your business stays online and operational, even during a partial or complete ISP outage. ```mermaid theme={null} graph LR subgraph "Normal Operation" User1[Users / LAN] --> R1{Router}; R1 -- "Primary Link (Active)" --> ISP1((Internet)); R1 -. "Secondary Link (Standby)" .-> ISP2((Internet)); end subgraph "During ISP Outage" User2[Users / LAN] --> R2{Router}; style R2 stroke:#f87171,stroke-width:2px R2 -.-> ISP3((Primary ISP Down)); style ISP3 stroke:#f87171,stroke-width:2px,stroke-dasharray: 5 5 R2 -- "Failover Link (Active)" --> ISP4((Internet)); end ``` ## Core Concepts Understanding these three concepts is key to mastering the WAN Failover service: Each of your internet connections is represented in SDX as a **WAN Tunnel**. This is a secure, lightweight OpenVPN tunnel that connects your router to Altostrat's global network over a specific physical interface (like `ether1` or `lte1`). This is a ranked list of your WAN Tunnels. The tunnel at the top of the list is the **primary** link, the second is the first backup, and so on. The system will always prefer to use the highest-priority link that is currently online. Altostrat continuously monitors the health of each WAN Tunnel by sending probes to our [global Anycast network](/sdx/en/resources/trusted-ips). If a link fails to respond, it is marked as `down`, and traffic is automatically rerouted to the next-highest priority link. ## Under the Hood: The Failover Mechanism Altostrat's WAN Failover is powered by a custom-built, high-performance **stateless route controller**, written in Go. Unlike a traditional VPN, its sole purpose is to authenticate your device and dynamically push routing information. This architecture is designed for maximum speed and resilience. ```mermaid theme={null} graph TD subgraph "MikroTik Router" A[WAN 1 Primary] C[WAN 2 Backup] end subgraph "Altostrat Cloud" B["Stateless Route Controller
(Go OpenVPN Server)"] D{Failover API} end A -->|"Establishes TCP Connection"| B C -->|"Establishes TCP Connection"| B B -->|"1\. Authenticates User/Pass"| D D -->|"2\. Returns Routes & Config"| B B -->|"3\. Pushes High-Priority Routes"| A B -->|"4\. Pushes Low-Priority Routes"| C ``` 1. **Stateless Connections:** Each of your router's WAN interfaces establishes a persistent TCP connection (over port 443 for firewall compatibility) to our route controller. The controller itself holds no state; it relies on the live TCP connection as proof that the link is up. 2. **Dynamic Route Pushing:** When a tunnel connects, it authenticates against our API. The API returns a set of routes tailored to that tunnel's priority. * **High-Priority Tunnels** receive more specific routes (e.g., `0.0.0.0/1` and `128.0.0.0/1`). * **Low-Priority Tunnels** receive a less specific, higher-metric default route (e.g., `0.0.0.0/0`). RouterOS naturally prefers the more specific routes, directing all traffic through the primary link. 3. **Instantaneous Failover:** If your primary ISP fails, the underlying TCP connection to our route controller is severed. The OpenVPN client on your MikroTik immediately detects this and **automatically withdraws** the specific, high-priority routes it had received. With those routes gone, the router's traffic immediately begins flowing to the next-best route available—the default route provided by your still-active backup tunnel. The failover is complete. *** ## Configuring WAN Failover Follow these steps to enable and configure WAN Failover on your site. When you first enable the service, Altostrat automatically creates two default, unconfigured WAN Tunnels for you to start with. From the SDX Dashboard, select the site you want to configure. In the site's overview, navigate to the **WAN Failover** tab. 1. Click **Enable** to activate the WAN Failover service for this site. 2. For your primary internet connection, click the **gear icon** to configure the first WAN Tunnel. 3. In the modal, define the connection details: * **Name:** A descriptive name (e.g., "Primary Fiber Link"). * **Interface:** Select the physical MikroTik interface (e.g., `ether1`, `lte1`). The platform queries your device in real-time to populate this list. * **Gateway IP:** Enter the gateway IP for this connection. Click **Look up eligible gateways** to have the platform attempt to auto-discover it for you. * **Connection Type:** Specify the type of link (Fiber, LTE, etc.) for identification. 4. Click **Save**. 5. Repeat this process for all your available WAN links. To add more than two, click **Add WAN Tunnel**. For metered connections like LTE or 5G, it's best to place them lower in the priority list to ensure they are only used as a last resort. The order of the tunnels in this list determines their failover priority. The link at the top is the primary, the second is the first backup, and so on. * Use the **up/down arrows** to drag and drop the tunnels into your desired order of preference. * Click **Confirm Priority** to save the changes and push the new configuration to your device. ## Managing and Monitoring Failover ### Manually Triggering a Failover You can manually trigger a failover for testing or operational reasons by simply changing the interface priority. 1. Navigate to the **WAN Failover** tab. 2. Drag your desired backup link to the top of the list. 3. Click **Confirm Priority**. The router will immediately prefer the new primary link and switch its active traffic path. A brief interruption in connectivity (a few seconds) will occur as the router's routing table converges and traffic switches to the new active link. ### Monitoring Failover Events When a WAN Tunnel goes down or comes back up, Altostrat logs this as a **Fault** event. This provides a complete historical record of your link stability and failover activity. To see a detailed history of all failover events, check the **Faults** log for your site. This is the best place to investigate ISP reliability. ### Deactivating WAN Failover If you no longer need a multi-WAN setup, you can deactivate the service. 1. Navigate to the **WAN Failover** tab. 2. Click the **Deactivate** button. 3. Confirm the action. Altostrat will dispatch jobs to remove all associated WAN tunnel configurations from the device. ## Best Practices Periodically test your failover by unplugging the primary link's network cable to ensure the backup connection takes over as expected. This validates your configuration and hardware from end to end. Place your most stable and highest-performing link at the top of the priority list. Use metered, high-latency, or less reliable connections (like LTE or satellite) as lower-priority backups. Use the **Faults** log to identify unstable connections that are failing and recovering frequently ("flapping"). A flapping link can cause network instability and should be investigated with the ISP. # Configuration Backups Source: https://altostrat.io/docs/sdx/en/fleet/configuration-backups Automate, manage, compare, and restore MikroTik configurations to ensure network integrity and enable rapid recovery from a secure, versioned history. Regular configuration backups are your most critical safety net, protecting against accidental misconfiguration, hardware failure, or other unexpected events. Altostrat SDX streamlines this process by providing a fully automated backup system. Every configuration snapshot is a human-readable `.rsc` script file, stored securely in the cloud for up to **12 months**. This versioned history gives you the tools to quickly compare changes, troubleshoot issues, and restore your network to a known-good state with confidence. ### How It Works: The Asynchronous Backup Process Backups in SDX are asynchronous jobs, ensuring reliability without interrupting your workflow. The platform uses a secure, temporary SFTP user to transfer the configuration file from your device directly to encrypted cloud storage. 1. **Initiation:** A backup is triggered either automatically by the daily schedule (at approximately 02:00 UTC) or manually when you click **Backup Now**. 2. **Job Dispatch:** SDX sends a job to the target device. 3. **Execution on Device:** The device receives the job on its next check-in. The job payload contains a script with unique, time-limited SFTP credentials. 4. **Secure Upload:** The device runs the `/export` command to generate the `.rsc` file and immediately uploads it via SFTP to a secure, private S3 bucket. The temporary SFTP user is valid only for this single transaction. 5. **Confirmation:** The backup file, named with a Unix timestamp (e.g., `1672531200.rsc`), appears in your dashboard. ```mermaid theme={null} graph TD subgraph "Initiation" A[SDX Dashboard or Daily Scheduler] -- "1\. Requests Backup" --> B{Job Queued}; end subgraph "Execution" B -- "2\. Device Polls & Receives Job" --> C[MikroTik Router]; C -- "3\. Executes backup script" --> C; end subgraph "Storage" C -- "4\. Securely Uploads .rsc file (SFTP)" --> D["Secure Cloud Storage (S3)"]; D -- "5\. Backup appears in UI" --> A; end ``` *** ## How-To Guides All backup operations for a device are managed from its Site Overview page. ### How to View and Manage Backups From your SDX Dashboard, click **Sites**, then select the site you want to manage. On the site's overview page, click the **Config Backups** tab. This displays a versioned list of all available backups, with the most recent at the top. From here, you can perform several key actions: * **Backup Now:** Trigger an immediate, on-demand backup. This is highly recommended before making significant configuration changes. * **Download:** Save a local copy of any `.rsc` script file. * **Compare:** Select two backups to see a line-by-line comparison of the changes. ### How to Compare Configurations (Diff View) The comparison tool (or "diff view") is essential for auditing changes or understanding what was modified between two points in time. 1. In the **Config Backups** list, check the boxes next to the two backups you want to compare. 2. A diff view will automatically appear, highlighting the differences: * Lines highlighted in red and prefixed with `-` were **removed**. * Lines highlighted in green and prefixed with `+` were **added**. ### How to Restore a Configuration Restoring a configuration allows you to revert a device to a previously known-good state. This is a manual, multi-step process designed for safety. Restoring a configuration will **overwrite the device's current settings**. This action will likely cause a reboot or a temporary loss of connectivity. **Always create a fresh on-demand backup before performing a restore.** From the **Config Backups** list in SDX, find the backup you want to restore and click the **Download** icon to save the `.rsc` file to your computer. Connect to your router using WinBox and open the **Files** window. Upload the downloaded `.rsc` file to the root directory of the device. The easiest way to upload is to simply drag and drop the `.rsc` file from your computer directly into the WinBox **Files** window. Once the upload is complete, open a **New Terminal** in WinBox. Type the `import` command followed by the name of your uploaded file and press Enter. For example, if your file is named `1672531200.rsc`, you would run: ```bash theme={null} import 1672531200.rsc ``` The router will execute the script, apply the configuration, and likely reboot. Once it comes back online, it will be running the restored configuration. *** ## Best Practices Always trigger an **on-demand backup** before performing major upgrades or reconfigurations. This gives you an immediate and precise rollback point. Before restoring, use the **diff tool** to confirm you are rolling back the exact changes you intend to. This prevents accidental reversion of other important updates. Use the [Orchestration Log](/sdx/en/fleet/introduction) to see a complete history of all backup jobs, including their status (Completed/Failed) and timestamps. # Control Plane Policies Source: https://altostrat.io/docs/sdx/en/fleet/control-plane-policies Define, enforce, and asynchronously deploy consistent firewall rules for management services like WinBox, SSH, and API across your entire MikroTik fleet. A **Control Plane Policy** is a centralized, reusable template that defines how your MikroTik devices should handle inbound management traffic. It is the foundation of secure, scalable network administration in Altostrat SDX. Instead of manually configuring firewall rules for services like WinBox, SSH, and the API on each individual device, you define a single policy in SDX. This policy is then applied to multiple sites, ensuring every router has a consistent and secure management posture. This "define once, apply everywhere" model eliminates configuration drift and drastically reduces the risk of human error. ### How It Works: Asynchronous Policy Deployment When you create or update a Control Plane Policy, the changes are not applied to your devices instantaneously. Instead, SDX uses a secure and resilient asynchronous workflow to ensure reliable delivery. 1. **Policy Update:** You modify a policy in the SDX dashboard. 2. **Job Dispatch:** The platform identifies all sites assigned to that policy and dispatches an individual `policy.updated` event for each one. 3. **Job Queuing:** This event is received by our backend, which creates a unique job for each site. This job contains the full, rendered firewall configuration based on the policy. 4. **Device Polling & Execution:** The next time a device checks in with the SDX platform (typically within 30 seconds), it receives the pending job, applies the new firewall rules, and reports back on the outcome. This asynchronous model ensures that policy changes are delivered reliably, even to devices on unstable or high-latency connections. ```mermaid theme={null} sequenceDiagram participant Admin participant SDX Dashboard participant Control Plane API participant Job Queue participant Device Admin->>SDX Dashboard: Edits "Corporate HQ" Policy SDX Dashboard->>Control Plane API: PUT /policies/{policyId} Control Plane API->>Control Plane API: Identify all assigned sites Control Plane API->>Job Queue: Dispatch 'policy.updated' job for each site loop Next Heartbeat Device->>+Job Queue: Poll for new jobs Job Queue-->>-Device: Return new firewall configuration end Device->>Device: Apply new firewall rules Device->>Job Queue: Report job status (completed/failed) ``` ### The Default Policy: Your Security Safety Net Your Altostrat workspace includes a **Default Control Plane Policy** out of the box. This policy serves two critical functions: 1. **Secure by Default:** When a new device is onboarded, it is automatically assigned the Default Policy. This policy provides a secure starting point by allowing management access only from private RFC1918 IP ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) and from Altostrat's own cloud IPs, while denying all other access. 2. **Fallback Protection:** If you delete a custom policy, any sites assigned to it are automatically reassigned to the Default Policy. This prevents devices from being left in an unsecured state with no management firewall. The Default Policy cannot be deleted, ensuring there is always a secure fallback configuration available for your fleet. *** ## How to Create and Manage Policies The workflow involves creating a policy, defining its rules, and then assigning it to the relevant sites. ### How to Create a Custom Policy In the SDX dashboard, go to **Policies → Control Plane**. You will see a list of your existing policies. Click **+ Add Policy** to open the configuration modal. Provide a descriptive **Name** for your policy, such as "Read-Only Access" or "Corporate HQ Security". Define the rules for your policy using the available settings. See the **Policy Configuration Options** section below for a detailed explanation of each field. * Add **Trusted Networks** (CIDRs). * Enable or disable **IP Services** and set their ports. * Toggle **Custom Input Rules** to manage rule precedence. When you are finished, click **Add** to save your new policy. The policy is now available to be assigned to sites. ### How to Assign a Policy to Sites A Control Plane Policy has no effect until it is assigned to one or more sites. 1. Navigate to the policy list and click on the policy you wish to assign. 2. In the policy editor, go to the **Sites** tab. 3. Select the sites you want this policy to apply to from the list of available sites. 4. Click **Save**. A `policy.updated` job will be dispatched to all newly assigned (and any removed) sites to update their configuration. *** ## Policy Configuration Options This is the primary IP whitelist for your policy. Only traffic originating from IP addresses or CIDR ranges in this list will be allowed to access the management services defined below. All other traffic will be dropped by default. **Best Practice:** Keep this list as restrictive as possible. Include your corporate office's static IP, your home IP, or a management VPN's IP range. This section allows you to enable or disable specific MikroTik management services and define their listening ports. The networks defined in **Trusted Networks** are automatically applied to all enabled services. * **WinBox:** Port `8291` by default. * **API:** Port `8728` by default. * **SSH:** Port `22` by default. The **API** service on port `8728` must remain enabled for Altostrat SDX to manage the device. Disabling it will disrupt communication and cause the device to appear offline. This advanced setting controls how your SDX policy interacts with any pre-existing, manually configured firewall rules on a device. * **Disabled (Default & Recommended):** The Altostrat policy takes full precedence. A `drop all` rule is placed at the end of the input chain, meaning **only** traffic explicitly allowed by this policy is permitted. This provides the most secure and predictable configuration. * **Enabled:** Your device's existing `input` chain rules are processed **before** the Altostrat `drop all` rule. This allows you to maintain custom firewall rules for specific edge cases while still benefiting from the centralized policy for management access. *** ## Best Practices Only allow access from the specific IP networks that absolutely need it. If a service like SSH is not part of your management workflow, disable it in the policy. Avoid making one-off firewall changes directly on devices. Instead, create a new, more specific policy in SDX and assign it to the relevant site(s). This maintains a single source of truth and prevents configuration drift. Use Control Plane Policies as your foundational security layer. Combine them with features like [Secure Remote Access](/sdx/en/fleet/secure-remote-access) for on-demand access and [Security Groups](/sdx/en/security/security-groups) for data plane traffic. # Introduction Source: https://altostrat.io/docs/sdx/en/fleet/introduction Learn the core principles of managing your MikroTik fleet at scale with Altostrat SDX, from centralized control and policy enforcement to secure remote access. Managing a network of distributed MikroTik routers can quickly become complex and inefficient. Manual configurations lead to inconsistencies, security postures vary from site to site, and a lack of centralized visibility makes troubleshooting a significant challenge. Altostrat SDX transforms this challenge by providing a powerful, centralized platform for fleet-wide orchestration, security, and visibility. We empower you to manage hundreds of devices as easily as one, ensuring consistency, security, and operational efficiency at scale. ```mermaid theme={null} graph TD subgraph "Altostrat SDX Cloud" A[Single Pane of Glass] end subgraph "Your Distributed Fleet" B[Site A: London Office] C[Site B: Retail Store #14] D[Site C: Data Center] E[...] end A -- "Manages & Monitors" --> B A -- "Manages & Monitors" --> C A -- "Manages & Monitors" --> D A -- "Manages & Monitors" --> E ``` ## The Pillars of Fleet Management Our fleet management capabilities are built on a few core principles, each designed to solve a specific operational challenge. The foundation of fleet management is a single source of truth. Our platform provides a centralized dashboard to create, view, and manage all your sites and devices, giving you a complete real-time overview of your network's health and status. Ensure consistency and eliminate configuration drift by defining your security and management rules once in a central policy. These policies are then applied to your entire fleet, guaranteeing that every device adheres to your desired operational posture. Securely access any device in your fleet, regardless of its location or network configuration. Our Management VPN and time-limited Transient Access credentials eliminate the need for open firewall ports or complex VPN setups, drastically reducing your attack surface. Protect your network with automated, daily configuration backups. With a full version history stored securely in the cloud, you can confidently make changes, audit modifications, and quickly restore a device to a known-good state. Move beyond IP addresses and device names. Enrich your fleet with structured tags, custom metadata, and file attachments to make your network searchable, understandable, and ready for advanced automation. ## In This Section Dive deeper into the features that power your fleet management workflow. Learn how to create, edit, and manage the lifecycle of your sites and their associated devices. Define and enforce consistent firewall rules for management services like WinBox and SSH. Access devices behind NAT securely with our Management VPN and Transient Access. Automate backups, compare configuration versions, and restore devices with confidence. Enrich your fleet with structured tags and custom data for enhanced organization. # Managing Sites and Devices Source: https://altostrat.io/docs/sdx/en/fleet/managing-sites-devices Learn how to create, edit, and delete sites, and understand the asynchronous lifecycle between a logical site and the physical MikroTik device it contains. In Altostrat SDX, effective fleet management begins with understanding the fundamental relationship between a **Site** and a **Device**, and the asynchronous way they communicate. * A **Site** is a logical container within the SDX platform. It is the central record that holds all configuration, policies, logs, metadata, and backups for a specific location or router. * A **Device** is the physical MikroTik router that you onboard and associate with a Site. All management actions, from applying policies to viewing logs, are performed at the Site level. This abstraction allows you to manage the role of a location, even if the underlying physical hardware changes. ```mermaid theme={null} graph TD subgraph Site["Site: Corporate HQ (site_...)"] A["Device: MikroTik RB5009
(hardware_hash: abc...)"] B[Control Plane Policy] C[Security Policy] D[Orchestration Log] E[Backups & Metadata] A --- B A --- C A --- D A --- E end ``` ## The Site Lifecycle A Site progresses through several states, from its initial creation in the dashboard to its final deletion. Understanding this lifecycle is key to managing your fleet effectively. ```mermaid theme={null} stateDiagram-v2 direction LR [*] --> Pending_Onboarding: Create Site in SDX Pending_Onboarding --> Online: Device runs bootstrap command and checks in Online --> Offline: Device stops sending heartbeats - has_pulse is false Offline --> Online: Device reconnects and sends heartbeat - has_pulse is true Online --> Deleting: Admin initiates deletion Offline --> Deleting: Admin initiates deletion Deleting --> Orphaned: Grace period ends, scheduler is removed from device ``` * **Pending Onboarding:** The Site has been created in SDX, but no physical device has been associated with it yet. * **Online:** The device is actively communicating with the SDX platform by sending regular heartbeats. Its `has_pulse` status is `true`. * **Offline:** The device has missed several consecutive heartbeat checks. SDX considers it unreachable, and its `has_pulse` status is `false`. * **Deleting:** An administrator has scheduled the site for deletion. A grace period begins, during which the device is sent commands to remove all Altostrat configuration and its bootstrap scheduler. * **Orphaned:** After deletion, the logical Site record is removed from SDX. The physical device stops communicating with the platform and has had all Altostrat configuration removed. It is now "orphaned" and can be factory reset or reconfigured as needed. ## How it Works: The Asynchronous Polling Model Altostrat SDX does not maintain a persistent, open connection *to* your devices. Instead, each managed device periodically connects *outbound* to the SDX platform to send a heartbeat and ask, "Are there any jobs for me?" This is known as a polling model. This architecture is fundamental to the platform's security and scalability: * **Enhanced Security:** You never need to open inbound firewall ports, drastically reducing your network's attack surface. * **NAT Traversal:** Devices can be managed from anywhere, even behind complex carrier-grade NAT, as they only need standard outbound internet access. * **Scalability:** The platform doesn't need to track thousands of open connections, making it highly scalable. ```mermaid theme={null} sequenceDiagram participant Device as MikroTik Router participant SDX as Altostrat SDX Platform loop Every 10-30 seconds Device->>+SDX: /poll (Heartbeat Check-in) SDX->>SDX: Update 'has_pulse' status & 'last_seen' time SDX->>SDX: Check for pending jobs for this site alt Job is available SDX-->>Device: 200 OK (with Job Payload) Device->>Device: Execute Job Script Device->>+SDX: /notify (Job Status: busy -> done/fail) SDX-->>-Device: 200 OK else No job available SDX-->>-Device: 304 Not Modified end end ``` This means that when you schedule a job or make a configuration change, it is queued. The action will only be executed the next time the device checks in, which is typically within 30 seconds. *** ## How-To Guides ### How to Create a New Site Every device must be associated with a site. The first step is to create this logical container. From the main menu in the SDX portal, click on **Sites**. Click the **+ Add** button. You will be prompted to give your new site a descriptive name (e.g., "Main Office - London", "Retail Store #14"). After naming it, the site is created with a `Pending Onboarding` status. From here, follow the Quickstart Guide to generate a bootstrap command and associate a physical device with this site. For a complete, step-by-step walkthrough of the device onboarding process, please refer to our Quickstart Onboarding guide. ### How to Edit Site Details You can change a site's name, location, and other metadata at any time. 1. Navigate to the **Sites** page and click on the site you wish to edit. 2. In the site overview, find the settings or details section. 3. Make your desired changes and click **Save**. Changes are applied immediately to the logical Site record in SDX. ### How to Delete a Site Deleting a site is a multi-stage process that removes the logical container from Altostrat and decommissions the associated device. When you delete a site, the associated MikroTik device will be **orphaned**. It will stop communicating with SDX, and its management tunnel will be torn down. SDX will automatically remove all Altostrat-applied configuration from the device during the deletion process. **This action cannot be undone.** 1. Navigate to the site's settings page and select the **Delete** option. 2. Confirm the action. The site's status will change to `Deleting`. 3. SDX will queue final jobs for the device, instructing it to remove all Altostrat configuration and its management scheduler. 4. After a grace period (approximately 10 minutes), all site assets—including logs, backups, and metrics—are permanently deleted, the device configuration is cleaned up, and the device becomes **Orphaned**. ## Best Practices Adopt a clear and predictable naming convention for your sites (e.g., `[Region]-[City]-[Function]`) to make your fleet easy to search and manage as it grows. Avoid making one-off configuration changes on individual devices. Instead, group sites with similar needs and apply shared [Control Plane Policies](/sdx/en/fleet/control-plane-policies) for security and management. The [Orchestration Log](/sdx/en/fleet/introduction) is your complete audit trail for all asynchronous jobs. Periodically review it to verify that automated tasks are running correctly and to track any changes made by your team. # Metadata, Tags, and Site Files Source: https://altostrat.io/docs/sdx/en/fleet/metadata-and-tags Learn how to enrich your fleet with structured tags for classification, custom metadata for specific data, and file attachments for documentation. As your network grows, keeping it organized is critical for efficient management, troubleshooting, and automation. Altostrat SDX provides three distinct but complementary tools to enrich your sites with contextual information: **Tags**, **Metadata**, and **Site Files**. Understanding when to use each tool is key to building a scalable and easily manageable network fleet. ### Choosing the Right Tool for the Job Each feature is designed to solve a different organizational problem. Use this guide to select the appropriate tool for your needs. **Purpose:** To categorize, group, and filter resources. Tags are structured, consistent, and reusable labels that apply across your fleet. They are the foundation for building dynamic automations and reports. **When to use:** For shared attributes that define a resource's role or group. * `Region: APAC` * `Site Status: Production` * `Customer Tier: Enterprise` **Purpose:** To store unique, unstructured, and specific data points for a single resource. Metadata is a free-form key-value store intended for storing information, not for classification. **When to use:** For data that is unique to a specific site or device. * `circuit_id: "AZ-54321-US"` * `local_contact: "jane.doe@example.com"` * `install_date: "2023-10-27"` **Purpose:** To attach rich content, documents, and visual aids directly to a site. This keeps all relevant human-readable documentation in one place. **When to use:** For files and notes that provide operational context. * `Network-Diagram.pdf` * `Rack-Photo.jpg` * `On-Site-Contacts.md` *** ## How to Manage Tags The tagging system in SDX is a two-step process: first, you create a tag **Definition** (the category), and then you apply it with a specific **Value** to your sites. This structure ensures consistency across your organization. A Tag Definition acts as the template for your tags (e.g., "Region," "Priority"). 1. Navigate to **Settings → Tags** in the SDX dashboard. 2. Click **+ Add Tag** to create a new definition. 3. Define the **Key** (the name of the category, like `Site Status`). 4. Choose a **Color** for easy visual identification in the UI. 5. Optionally, mark the tag as **mandatory** for certain resource types (e.g., require all `sites` to have a `Site Status` tag). 6. Click **Save**. Your new tag category is now available to be used. Once a definition exists, you can apply it to any resource. 1. Navigate to the overview page of the site you want to tag. 2. Find the **Tags** section and click **Add Tag**. 3. Select the **Tag Definition** you created (e.g., `Site Status`). 4. Enter the specific **Value** for this site (e.g., `Production`). Our system supports auto-completion based on existing values for that tag, enforcing case-insensitive uniqueness to prevent variations like "Production" and "production". 5. The tag is now applied. You can add multiple tags to a single site. Once tagged, use the filter controls on the main **Sites** page to instantly find all resources that match a specific tag and value (e.g., show all sites where `Region` is `APAC`). *** ## How to Manage Metadata and Site Files Metadata and Site Files are managed directly from a site's overview page, providing a dedicated space for resource-specific information. 1. Navigate to the site you want to manage. 2. Select the **Metadata** or **Files** tab. 3. From here, you can perform several actions: * **Add Metadata:** Create new key-value pairs to store specific information. Values can be strings, numbers, or booleans. * **Upload Files:** Securely attach documents (`.pdf`, `.docx`), images (`.jpg`, `.png`), or other media. * **Create Notes:** Write and save notes directly in Markdown format for quick reference. All Site Files are stored securely and can only be accessed via authenticated, time-limited signed URLs, ensuring your documentation remains protected. ## Best Practices Before creating tags, plan a consistent taxonomy for your organization. A well-defined set of tags is far more powerful for filtering and automation than dozens of ad-hoc ones. Think about how you want to group and report on your resources. Remember the core difference: **tags are for filtering**, while **metadata is for storing reference data**. Don't put a unique circuit ID in a tag, as it creates a tag value that only applies to one resource. Place it in metadata instead. Tags are a key component of automation. Use them as filters or conditions in your [Workflows](/sdx/en/automation/workflows/building-workflows) to perform actions on specific groups of sites (e.g., "Run a health check on all sites with the tag `Site Status: Production`"). # Secure Remote Access Source: https://altostrat.io/docs/sdx/en/fleet/secure-remote-access Securely access any MikroTik device using the Management VPN and time-limited Transient Access credentials, without exposing ports or configuring complex firewall rules. import { Steps, Card, CardGroup, Columns, Note, Warning } from 'mintlify'; Altostrat SDX solves one of the most common challenges in network management: securely accessing devices that are behind NAT or restrictive firewalls. Our approach eliminates the need for complex port forwarding, static VPNs, or exposing management interfaces to the internet, dramatically reducing your network's attack surface. This is achieved through two core components working together in a layered security model: When a device connects to Altostrat, it establishes a persistent, outbound OpenVPN tunnel to our global network of regional servers. This encrypted tunnel acts as a secure, private control plane, allowing SDX to manage the device without requiring **any** inbound ports to be opened on your firewall. Instead of using permanent, high-privilege accounts, SDX allows you to generate **Transient Access** credentials. These are unique, time-limited logins for WinBox or SSH that are created on-demand when you need them and are automatically revoked when they expire or are manually terminated. ### How It Works: The Secure Connection Flow Your remote session is securely proxied through the Altostrat SDX cloud infrastructure. When you request access, the platform orchestrates a series of asynchronous jobs to build and tear down a secure, temporary pathway to your device. ```mermaid theme={null} sequenceDiagram participant Admin participant SDX Platform participant Regional Server participant Device Admin->>+SDX Platform: 1. Request Transient Access SDX Platform->>SDX Platform: 2. Generate credentials & random port SDX Platform->>Regional Server: 3. Job 1: Create secure NAT rule (Public Port -> Tunnel IP) SDX Platform->>Device: 4. Job 2: Create temporary user SDX Platform-->>-Admin: 5. Display Endpoint, Port & Credentials Admin->>+Regional Server: 6. Connect via WinBox/SSH Regional Server-->>-Device: 7. Proxy connection via Management VPN ``` 1. **Request:** You initiate a Transient Access request from the SDX dashboard. 2. **Generation:** The platform generates a unique username, a strong random password, and selects a random high-numbered port (e.g., `48152`) on the appropriate regional server. 3. **Orchestration:** Two asynchronous jobs are dispatched: * **Job 1 (Regional Server):** A job is sent to the regional server responsible for your device's Management VPN. It creates a temporary, secure NAT rule that maps the public-facing random port to the private IP address of your device's management tunnel. * **Job 2 (Device):** A second job is queued for your MikroTik device. The next time it checks in (usually within seconds), it receives a command to create a temporary user with the generated credentials and appropriate permissions (`read-only` or `full`). 4. **Connection:** You use the provided credentials to connect to the regional server's public endpoint on the assigned port. The server securely proxies your connection through the Management VPN directly to your device. 5. **Revocation:** When the session expires or you manually revoke it, corresponding jobs are dispatched to delete the temporary user from the device and tear down the NAT rule on the regional server, leaving no trace of the access path. *** ## How to Generate Transient Access Credentials This guide walks you through generating on-demand credentials to connect to your device via WinBox or SSH. From the Altostrat SDX dashboard, select **Sites** from the main menu and click on the site you wish to access. In the site overview, click on the **Transient Access** tab. This will display a list of any currently active sessions. Click the **+ Add** button to create a new session. Configure the access parameters for your session: * **Access Type:** Select `WinBox` or `SSH`. * **Permissions:** Choose `Full` for administrative rights or `Read Only` for viewing configuration without the ability to make changes. * **Source IP (CIDR):** For added security, this field defaults to your current public IP. Only connections from this IP or CIDR range will be allowed. * **Expiration:** Set the duration for which the credentials will be valid (e.g., 1 hour). The maximum is 24 hours. Click **Add** to dispatch the jobs that generate the credentials and open the secure connection. SDX will display the generated **Endpoint** (the regional server's hostname), **Port**, **Username**, and **Password**. * **For WinBox:** Copy the credentials into your WinBox client and click **Connect**. * **For SSH:** Use the credentials in your preferred SSH client: `ssh @ -p ` **One-Click Connect:** If you have our helper application installed, you can click the **Winbox** button next to the credentials to automatically launch and log into the WinBox session. ## Managing Active Sessions You can view all active sessions and revoke access at any time before the scheduled expiration. 1. Return to the **Transient Access** tab for the site. 2. Locate the session in the **Active Credentials** list. 3. Click **Revoke** to immediately dispatch jobs that invalidate the credentials, terminate the session, and remove the secure access path. ## Related Feature: Transient Port Forwarding While Transient Access is for managing the router itself, **Transient Port Forwarding** allows you to securely access a device *on the LAN behind* the router (e.g., a web server, camera, or IoT device) without a VPN. Explore how to create temporary, secure port forwards to internal devices. ## Best Practices Always grant access for the shortest time necessary to complete your task. This adheres to the principle of least privilege and minimizes the attack window. Whenever possible, restrict access to a specific source IP address or a trusted network range using the **Source IP (CIDR)** field. Never use `0.0.0.0/0` unless absolutely necessary. If a task only requires viewing configuration (e.g., for troubleshooting), always generate `Read Only` credentials instead of granting full administrative access. # Core Concepts Source: https://altostrat.io/docs/sdx/en/getting-started/core-concepts Understand the fundamental building blocks of the Altostrat SDX platform, including Sites, Policies, the Management VPN, Automation, and your Account Hierarchy. Before you dive in, it's important to understand the core concepts that make the Altostrat SDX platform so powerful. This page introduces the fundamental building blocks and how they fit together to provide a centralized, secure, and automated network management experience. ## The Altostrat SDX Architecture At a high level, your account is structured into **Teams** which contain your network **Sites**. These sites are managed via **Policies** and automated by our **Automation Engine**, all communicating securely through the central **Management VPN**. ```mermaid theme={null} graph TD subgraph "Your Account Hierarchy" A[Organization] --> B[Workspace]; B --> C[Team]; end subgraph "Platform Management" C -- "Contains & Manages" --> D[Sites & Policies]; E[Automation & AI Engine] -- "Orchestrates" --> D; end subgraph "Network Resources" F[MikroTik Device]; D -- "Are deployed to" --> F; end subgraph "Secure Backbone" style VPN stroke-dasharray: 5 5 E --> VPN(Management VPN); D --> VPN; VPN --> F; end ``` ## The Five Fundamental Building Blocks A **Site** is the logical container in SDX for your physical MikroTik router (the **Device**). All management, monitoring, and policy application happens at the Site level. This is the atomic unit of your fleet. The secure backbone of the entire platform. This is the encrypted, always-on tunnel automatically established between your device and our cloud. It enables all management actions without requiring you to open any inbound firewall ports. The principle of "define once, apply everywhere." Policies are reusable templates for your firewall rules, content filters, and threat mitigation settings. You create a policy and apply it to hundreds of sites to ensure perfect consistency. The engine that moves you from manual tasks to intelligent orchestration. It includes three powerful tools: the visual **Workflow** builder, centralized **Script Management**, and the conversational **AI Co-pilot**. The structure that holds everything together. Your account is organized into a hierarchy of **Organizations**, **Workspaces**, and **Teams**. This model provides the foundation for multi-tenancy, billing, and role-based access control. ## Ready to Get Started? Now that you understand the core concepts, the best way to learn is by doing. Our quickstart guide will walk you through the process of bringing your first device online in minutes. Follow our step-by-step tutorial to connect your prepared MikroTik router to the Altostrat SDX platform. # Introduction to Altostrat SDX Source: https://altostrat.io/docs/sdx/en/getting-started/introduction Altostrat SDX is a software-defined networking platform designed to unlock the full potential of your MikroTik hardware, transforming distributed networks into a centrally managed, secure, and automated fabric.