Authentication

Learn how to securely authenticate with the ViewAI API using API keys, environment variables, and configuration options.

Overview

The ViewAI SDK uses API key authentication to secure access to the platform. API keys are unique identifiers that authenticate your applications and track usage.

Getting an API Key

1

Create an Account

• Visit https://app.viewai.ca

• Sign up for a free account

• Verify your email address

2

Generate API Key

• Log in to your ViewAI dashboard

• Navigate to Settings → API Keys

• Click Generate New API Key

• Copy your API key (you won't be able to see it again!)

• Store it securely

Warning: Never commit API keys to version control or share them publicly.

Authentication Methods

Method 1: Direct API Key (Quick Testing)

Pass your API key directly when initializing the client:

example.py

from viewai_client import ViewAIClient

client = ViewAIClient(api_key="your-api-key-here")

Use Case: Quick testing, interactive sessions, Jupyter notebooks

⚠️ Warning: Not recommended. API key is visible in code.

Method 2: Environment Variables (Recommended)

The most secure method for production applications:

example.py

import os
from viewai_client import ViewAIClient

# SDK automatically reads from environment
client = ViewAIClient(api_key=os.getenv("VIEWAI_API_KEY"))

# Or let SDK auto-discover
client = ViewAIClient()  # Looks for VIEWAI_API_KEY env var

Setting Environment Variables:

shell

# Linux/macOS
export VIEWAI_API_KEY="your-api-key-here"

# Windows Command Prompt
set VIEWAI_API_KEY=your-api-key-here

# Windows PowerShell
$env:VIEWAI_API_KEY="your-api-key-here"

Use Case: Production applications, CI/CD pipelines, Docker containers

Method 3: Configuration File

Use a .env file with python-dotenv:

.env file:

.env

VIEWAI_API_KEY=your-api-key-here
VIEWAI_BASE_URL=https://api.viewai.ca
VIEWAI_TIMEOUT=30
VIEWAI_MAX_RETRIES=3

Python code:

example.py

from dotenv import load_dotenv
from viewai_client import ViewAIClient

# Load environment variables from .env
load_dotenv()

# Initialize client
client = ViewAIClient()  # Auto-reads from environment

Use Case: Local development, team collaboration

Important: Add .env to your .gitignore!

Method 4: Configuration Object

For advanced configuration:

example.py

from viewai_client import ViewAIClient
from viewai_client.config import ClientConfiguration

config = ClientConfiguration(
    api_key="your-api-key-here",
    base_url="https://api.viewai.ca",
    timeout=60,
    max_retries=5,
    default_workspace="production"
)

client = ViewAIClient(config=config)

Use Case: Complex applications, custom configurations

Verifying Authentication

Always verify your authentication before performing operations:

example.py

from viewai_client import ViewAIClient

client = ViewAIClient(api_key="your-api-key")

# Method 1: Check authentication
auth_check = client.health.check_authentication()
if auth_check.healthy:
    print("✓ Authentication successful")
    print(f"  Workspaces available: {auth_check.details.get('workspace_count')}")
else:
    print(f"✗ Authentication failed: {auth_check.message}")

# Method 2: Try accessing workspaces
try:
    workspaces = client.list_accessible_workspaces()
    print(f"✓ Authenticated! Access to {len(workspaces)} workspaces")
except Exception as e:
    print(f"✗ Authentication error: {e}")

Security Best Practices

Never expose your API keys in source code or logs. The examples below show bad and good practices for handling keys.

Never Hardcode API Keys

❌ Bad:

bad.py

client = ViewAIClient(api_key="vk_abc123...")  # Visible in code!

✅ Good:

good.py

client = ViewAIClient(api_key=os.getenv("VIEWAI_API_KEY"))

Use Environment Variables

Store API keys in environment variables or secret management systems:

shell

# .bashrc or .zshrc
export VIEWAI_API_KEY="your-api-key"

# Or use a secrets manager
export VIEWAI_API_KEY=$(aws secretsmanager get-secret-value --secret-id viewai-key --query SecretString --output text)

Rotate API Keys Regularly

1

Generate a new API key in the dashboard

2

Update your environment variables

3

Test with the new key

4

Revoke the old key

Use Different Keys for Different Environments

shell

# Development
export VIEWAI_API_KEY="vk_dev_..."

# Staging
export VIEWAI_API_KEY="vk_staging_..."

# Production
export VIEWAI_API_KEY="vk_prod_..."

Restrict API Key Permissions

In your ViewAI dashboard:

• Set IP whitelist restrictions

• Limit workspace access

• Set rate limits

• Enable monitoring and alerts

Don't Log API Keys

❌ Bad:

bad_logging.py

print(f"Using API key: {api_key}")  # Exposed in logs!

✅ Good:

good_logging.py

print(f"Using API key: {api_key[:8]}...")  # Only show prefix

Platform-Specific Setup

Docker

Dockerfile:

Dockerfile

FROM python:3.10-slim

WORKDIR /app

# Install SDK
RUN pip install viewai-client

# Don't hardcode API key!
ENV VIEWAI_API_KEY=""

COPY . .

CMD ["python", "app.py"]

docker-compose.yml:

docker-compose.yml

version: '3.8'

services:
  app:
    build: .
    environment:
      - VIEWAI_API_KEY=${VIEWAI_API_KEY}
    env_file:
      - .env

Usage:

shell

# Pass API key at runtime
docker run -e VIEWAI_API_KEY="your-key" your-image

# Or use docker-compose
VIEWAI_API_KEY="your-key" docker-compose up

Kubernetes

Secret:

secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: viewai-secrets
type: Opaque
stringData:
  api-key: "your-api-key-here"

Deployment:

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: viewai-app
spec:
  template:
    spec:
      containers:
      - name: app
        image: your-app:latest
        env:
        - name: VIEWAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: viewai-secrets
              key: api-key

AWS

Using AWS Secrets Manager:

example.py

import boto3
import json
from viewai_client import ViewAIClient

def get_secret():
    client = boto3.client('secretsmanager', region_name='us-east-1')
    response = client.get_secret_value(SecretId='viewai-api-key')
    return json.loads(response['SecretString'])['api_key']

# Use the secret
api_key = get_secret()
viewai_client = ViewAIClient(api_key=api_key)

GitHub Actions

.github/workflows/deploy.yml:

deploy.yml

name: Deploy

on: [push]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.10'

      - name: Install dependencies
        run: |
          pip install viewai-client

      - name: Run deployment
        env:
          VIEWAI_API_KEY: ${{ secrets.VIEWAI_API_KEY }}
        run: |
          python deploy.py

Add secret in GitHub: Settings → Secrets → Actions → New repository secret

Configuration Options

Complete Configuration Example

example.py

from viewai_client import ViewAIClient
from viewai_client.config import ClientConfiguration
import logging

config = ClientConfiguration(
    # Authentication
    api_key=os.getenv("VIEWAI_API_KEY"),

    # API Endpoint
    base_url="https://api.viewai.ca",

    # Timeouts (seconds)
    connection_timeout=10,
    read_timeout=300,

    # Retry Strategy
    max_retries=5,
    retry_backoff_factor=2.0,

    # Defaults
    default_workspace="production",
    default_project="ml-models",
    default_model_id=None,

    # Logging
    log_level=logging.INFO,
    log_file="viewai.log"
)

client = ViewAIClient(config=config)

Environment Variables Reference

Variable	Description	Default
VIEWAI_API_KEY	Your API key	Required
VIEWAI_BASE_URL	API endpoint	https://api.viewai.ca
VIEWAI_TIMEOUT	Request timeout (seconds)	30
VIEWAI_MAX_RETRIES	Maximum retry attempts	3
VIEWAI_LOG_LEVEL	Logging level	INFO

Error Handling

Handle authentication errors gracefully:

example.py

from viewai_client import ViewAIClient
from viewai_client.exceptions import AuthenticationError, APIError

try:
    client = ViewAIClient(api_key=api_key)
    workspaces = client.list_accessible_workspaces()

except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
    print("Please check your API key")

except APIError as e:
    print(f"API error: {e.message}")
    print(f"Status code: {e.status_code}")

except Exception as e:
    print(f"Unexpected error: {e}")

Testing Authentication

Create a test script:

test_auth.py

#!/usr/bin/env python3
"""Test ViewAI authentication."""

import sys
from viewai_client import ViewAIClient

def test_auth(api_key: str) -> bool:
    """Test if API key is valid."""
    try:
        client = ViewAIClient(api_key=api_key)

        # Test connection
        health = client.health.check_connection()
        if not health.healthy:
            print(f"✗ Connection failed: {health.message}")
            return False

        # Test authentication
        auth = client.health.check_authentication()
        if not auth.healthy:
            print(f"✗ Authentication failed: {auth.message}")
            return False

        # Test workspace access
        workspaces = client.list_accessible_workspaces()

        print("✓ Authentication successful!")
        print(f"  Connection time: {health.response_time_ms:.0f}ms")
        print(f"  Workspaces accessible: {len(workspaces)}")
        return True

    except Exception as e:
        print(f"✗ Error: {e}")
        return False

if __name__ == "__main__":
    import os
    api_key = os.getenv("VIEWAI_API_KEY")

    if not api_key:
        print("Error: VIEWAI_API_KEY environment variable not set")
        sys.exit(1)

    success = test_auth(api_key)
    sys.exit(0 if success else 1)

Run the test:

shell

python test_auth.py

Troubleshooting

Issue: Authentication Failed

Check:

• Is your API key correct?

• Has the key been revoked?

• Are there IP restrictions?

• Is the key expired?

Solution:

check_format.py

# Verify API key format
if not api_key.startswith("vk_"):
    print("Invalid API key format")

# Check key length
if len(api_key) < 32:
    print("API key too short")

Issue: Connection Timeout

Solution:

example.py

config = ClientConfiguration(
    api_key=api_key,
    connection_timeout=30,  # Increase timeout
    max_retries=5          # More retry attempts
)
client = ViewAIClient(config=config)

Issue: Rate Limit Exceeded

Solution:

example.py

from time import sleep

# Implement exponential backoff
for attempt in range(5):
    try:
        result = client.predict(data, model_id)
        break
    except APIError as e:
        if e.status_code == 429:  # Rate limit
            wait = 2 ** attempt
            print(f"Rate limited. Waiting {wait}s...")
            sleep(wait)
        else:
            raise

Next Steps

• 📘 Core Concepts - Understand workspaces and projects

• 🚀 Quick Start - Build your first model

• 🔐 Best Practices - Production security patterns

Additional Resources

• https://app.viewai.ca/settings/api-keys

• /advanced/best-practices.md#security

• mailto:[email protected]

Security Question? Contact [email protected]