Project

alta_labs

0.0
The project is in a healthy, maintained state
alta_labstwilightcoders/alta_labsHomepageDocumentationSource CodeBug Tracker
A Ruby client library for interacting with the Alta Labs cloud management platform. Manage sites, devices, WiFi networks, and more programmatically.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
156
Stars
0
Forks
0
Watchers
0
 Releases
Current version
0.1.1
Total releases
2
First release
2026-03-31
Latest release
2026-03-31
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-03-31
Reverse Dependencies
0

 Dependencies

Development

bundler
~> 2.0
climate_control
~> 1.0
pry-byebug
~> 3
rake
~> 13.0
rspec
~> 3.0
simplecov
~> 0.22
simplecov-json
~> 0.2
vcr
~> 6.0
webmock
~> 3.0

Runtime

base64
~> 0.2
faraday
~> 2.0
faraday-retry
~> 2.0
 Project Readme

Gem Version Build Status Coverage

AltaLabs

A Ruby SDK for the Alta Labs cloud management API. Manage sites, devices, WiFi networks, and more programmatically.

Note: Alta Labs does not currently publish public API documentation. This library was built by reverse-engineering the web management portal at manage.alta.inc. While functional, the API surface may change without notice.

Installation

Add to your Gemfile:

gem 'alta_labs'

Or install directly:

$ gem install alta_labs

Usage

Authentication

The SDK authenticates with Alta Labs via AWS Cognito SRP — the same mechanism used by the web portal. No AWS SDK dependency is required; SRP is implemented natively.

require 'alta_labs'

client = AltaLabs::Client.new(
  email: 'you@example.com',
  password: 'your-password'
)

# Authentication happens automatically on the first API call,
# or you can authenticate explicitly:
client.authenticate

You can also configure via environment variables or a block:

# Environment variables (ALTA_LABS_EMAIL, ALTA_LABS_PASSWORD)
client = AltaLabs::Client.new

# Block configuration
AltaLabs.configure do |config|
  config.email = 'you@example.com'
  config.password = 'your-password'
  config.timeout = 60
end

Sites

# List all sites
sites = client.sites.list
# => [{"id" => "abc123", "name" => "Main Office", "online" => 5, ...}]

# Get site detail
site = client.sites.find(id: 'abc123')
# => {"id" => "abc123", "tz" => "America/Denver", "vlans" => [...], ...}

# Site audit log
audit = client.sites.audit(id: 'abc123')
audit['trail'].each do |entry|
  puts "[#{entry['ts']}] #{entry['action']} #{entry['type']}"
end

# Create a site
client.sites.create(name: 'New Site', type: 'residential')

# Rename a site
client.sites.rename(id: 'abc123', name: 'Updated Name')

Devices

# List devices for a site
devices = client.devices.list(site_id: 'abc123')

# Add a device by serial number
client.devices.add_serial(site_id: 'abc123', serial: 'ALTA-XXXX')

# Move a device between sites
client.devices.move(id: 'device-id', site_id: 'new-site-id')

WiFi / SSIDs

# List SSIDs for a site
result = client.wifi.list(site_id: 'abc123')
result['ssids'].each do |ssid|
  puts "#{ssid['ssid']} (#{ssid.dig('config', 'security')})"
end

# Get a specific SSID
ssid = client.wifi.find(id: 'ssid-id')

Account

# Get account info (requires access_token)
info = client.account.info

Content Filtering

# Get content filter settings
filter = client.filters.get_filter(site_id: 'abc123')
# => {"blockedRegions" => ["CN"], "blockWired" => true, ...}

Profiles

profiles = client.profiles.list(site_ids: ['abc123'])

Floor Plans

floors = client.floor_plans.floors(site_id: 'abc123')

Token Management

Tokens are automatically refreshed when they expire. The SDK handles:

  • Initial SRP authentication with Cognito
  • JWT token storage and expiration tracking
  • Automatic token refresh using the refresh token
  • MFA challenges (raises AltaLabs::MfaRequiredError with session data)

MFA Support

If MFA is enabled on the account:

begin
  client.authenticate
rescue AltaLabs::MfaRequiredError => e
  # Prompt user for MFA code
  client.auth.verify_mfa(
    code: '123456',
    session: e.session,
    challenge_name: e.challenge_name
  )
end

Error Handling

begin
  client.sites.find(id: 'nonexistent')
rescue AltaLabs::AuthenticationError => e
  # Invalid credentials or expired session
rescue AltaLabs::NotFoundError => e
  # Resource not found
rescue AltaLabs::RateLimitError => e
  # Too many requests
rescue AltaLabs::ServerError => e
  # Alta Labs server error
rescue AltaLabs::ApiError => e
  # Generic API error
  puts e.status # HTTP status code
  puts e.body   # Response body
end

Configuration Options

Option Default Description
email ENV['ALTA_LABS_EMAIL'] Account email
password ENV['ALTA_LABS_PASSWORD'] Account password
api_url https://manage.alta.inc API base URL
timeout 30 Request timeout (seconds)
open_timeout 10 Connection open timeout (seconds)

Self-Hosted Controller

To use with a self-hosted Alta Control instance:

client = AltaLabs::Client.new(
  email: 'you@example.com',
  password: 'your-password',
)
client.config.api_url = 'https://your-controller.local'

Development

$ bundle install
$ bundle exec rspec
$ bin/console

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b feature/my-feature)
  3. Commit your changes (git commit -am 'Add my feature')
  4. Push to the branch (git push origin feature/my-feature)
  5. Create a Pull Request

License

MIT License. See LICENSE.txt.