Authentication

API Key Setup

Contact support@asoba.co to obtain an API key. A single key works for all API-key-protected endpoints:

Inverter Telemetry
OODA Terminal Alerts
Partner API

export ASOBA_API_KEY=<your_api_key>

The SDK sends this value as the x-api-key header on every request to those APIs. Endpoint URLs are hardcoded to production defaults.

For AWS-backed services (Forecasting, Terminal internals, Data Ingestion, Training), use standard AWS credentials instead of an API key:

export AWS_ACCESS_KEY_ID=<your_access_key>
export AWS_SECRET_ACCESS_KEY=<your_secret_key>
export AWS_REGION=af-south-1

Environment Variables per Endpoint

Endpoint	Env Var	Header
Inverter Telemetry / OODA / Partner	`ASOBA_API_KEY`	`x-api-key`
Auth Service	`ASOBA_AUTH_ENDPOINT` (URL only)	`Authorization: Bearer <token>`
Energy Analyst	`ENERGY_ANALYST_URL` (URL only)	No auth header
Edge Registry	`EDGE_API_URL` (URL only)	No auth header

Multi-Endpoint Configuration Pattern

If an API key is missing when a protected client is used, the SDK raises AuthenticationError (or ConfigurationError where an endpoint override is invalid).

from asoba import OnaClient

# Picks up ASOBA_API_KEY automatically
client = OnaClient()

# Or pass the key explicitly
client = OnaClient(api_key='<your_api_key>')

const { OnaSDK } = require('@asobacloud/sdk');

const sdk = new OnaSDK();
// or: new OnaSDK({ apiKey: '<your_api_key>' });

Auth Service (Python Only)

The Python SDK includes an AuthClient for user authentication, MFA, token management, and API key introspection. The JavaScript SDK does not include an auth client. Terminal API calls that require a user JWT should go through client.auth.login() first.

from asoba import OnaClient

client = OnaClient(auth_endpoint='https://auth-api.asoba.co/prod')

# Login
result = client.auth.login('user@example.com', 'password')

# Handle MFA if required
if result.get('mfa_required'):
    if result.get('mfa_enrollment'):
        # First-time MFA setup — display provisioning_uri as a QR code
        print(f"Setup MFA: {result['provisioning_uri']}")

    # Verify MFA code from authenticator app
    result = client.auth.verify_mfa(result['mfa_token'], '123456')

# Token is automatically stored in the client
print(f"Logged in as: {result['user']['username']}")

Token Management

# Set token directly (for external integrations / SSO)
client.auth.set_token('eyJhbGciOiJIUzI1NiIs...')

# Get current user from token
user = client.auth.get_current_user()
print(f"User: {user['username']} (Role: {user['role_id']})")

# Refresh token before expiry
new_token = client.auth.refresh_token()

# Check authentication status
if client.auth.is_authenticated():
    print("Authenticated")

# Logout (clears local token)
client.auth.logout()

API Key Introspection

# Get API key information
info = client.auth.get_api_key_info('opa_prod_xxxxx')
print(f"Expires: {info['expires_at']}")
print(f"Sites: {info['permitted_site_ids']}")
print(f"Expired: {info['is_expired']}")

# Validate API key for a specific site
validation = client.auth.validate_api_key('opa_prod_xxxxx', 'Sibaya')
if validation['valid']:
    print("API key is valid for site")

Token Exchange (SSO Integration)

# Exchange external token for Ona token
result = client.auth.exchange_token(
    external_token='external_jwt_token',
    provider='external-sso'
)
print(f"Ona token: {result['token']}")

Auth Service Configuration

export ASOBA_AUTH_ENDPOINT=https://auth-api.asoba.co/prod

The auth endpoint must use HTTPS — the SDK raises ConfigurationError otherwise. The Lambda function name is derived from the endpoint URL:

Endpoint contains	Lambda function
`staging`	`ona-user-auth-staging`
`dev` or `localhost`	`ona-user-auth-dev`
(default)	`ona-user-auth-prod`

Authorization Header

The AuthClient.get_auth_header() method returns a dict with the Authorization header for use in custom HTTP requests:

headers = client.auth.get_auth_header()
# {'Authorization': 'Bearer eyJhbGciOiJIUzI1NiIs...'}

Troubleshooting

Error	Cause	Solution
`401 Unauthorized`	Invalid or missing API key	Verify `ASOBA_API_KEY`; contact support@asoba.co
`403 Forbidden`	API key not scoped to site	Request access to the `site_id` you’re querying
`AuthenticationError`	Token expired or invalid	Call `login()` or `refresh_token()`
`ConfigurationError`	Invalid endpoint scheme/config	Check HTTPS endpoints and env vars

Next Steps

Error Handling — error classes and retry logic
Installation — full env-var reference
Service Guides — browse service documentation