Authentication

The Ashr Labs SDK uses API keys for authentication. This guide covers everything you need to know about API key authentication.

API Key Format

API keys follow a specific format:

• Prefix: tp_ (Ashr Labs)
• Length: 32+ characters after the prefix
• Example: tp_abc123def456ghi789jkl012mno345pq

Creating an API Key

API keys can only be created through the dashboard (for security reasons):

1. Log in at lab.ashr.io
2. Click API Keys in the sidebar
3. Click Create New Key
4. Configure your key:
   • Name: A descriptive name (e.g., "CI/CD Pipeline", "Local Development")
   • Expiration: Choose 30 days, 90 days, 1 year, or never
5. Click Create
6. Important: Copy the key immediately — it will only be shown once!

Using the API Key

Basic Usage

from ashr_labs import AshrLabsClient

# Only need API key — base_url defaults to production
client = AshrLabsClient(api_key="tp_your_api_key_here")

Environment Variables (Recommended)

Store your API key in an environment variable and use from_env():

export ASHR_LABS_API_KEY="tp_your_api_key_here"

from ashr_labs import AshrLabsClient

# Reads ASHR_LABS_API_KEY (required) and ASHR_LABS_BASE_URL (optional)
client = AshrLabsClient.from_env()

Configuration File

For local development, you can use a configuration file (add to .gitignore):

# config.py (DO NOT COMMIT)
API_KEY = "tp_your_api_key_here"

from ashr_labs import AshrLabsClient
import config

client = AshrLabsClient(api_key=config.API_KEY)

API Key Permissions

API keys have limited permissions compared to OAuth authentication. Here's what API keys can access:

Operation	API Key Access
get_dataset	Yes
list_datasets	Yes
create_run	Yes
get_run	Yes
list_runs	Yes
delete_run	Yes
create_request	Yes
get_request	Yes
list_requests	Yes
list_api_keys	Yes
revoke_api_key	Yes
create_api_key	No (OAuth only)
Tenant management	No (OAuth only)
User management	No (OAuth only)
File uploads	No (OAuth only)

Managing API Keys

List Your API Keys

api_keys = client.list_api_keys()
for key in api_keys:
    print(f"Key: {key['key_prefix']}... | Name: {key['name']}")
    print(f"  Created: {key['created_at']}")
    print(f"  Last used: {key.get('last_used_at', 'Never')}")
    print(f"  Active: {key['is_active']}")

Revoke an API Key

# Revoke a specific API key
client.revoke_api_key(api_key_id=123)
print("API key revoked successfully")

Include Inactive Keys

# List all keys, including revoked ones
all_keys = client.list_api_keys(include_inactive=True)

Security Best Practices

1. Never Commit API Keys

Add to your .gitignore:

# API keys and secrets
.env
config.py
*_secret*
*_key*

2. Use Environment Variables in CI/CD

# GitHub Actions example
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      ASHR_LABS_API_KEY: ${{ secrets.ASHR_LABS_API_KEY }}
    steps:
      - run: python run_tests.py

3. Rotate Keys Regularly

Create new keys periodically and revoke old ones:

# List keys and check age
from datetime import datetime, timedelta

api_keys = client.list_api_keys()
for key in api_keys:
    created = datetime.fromisoformat(key["created_at"].replace("Z", "+00:00"))
    age = datetime.now(created.tzinfo) - created

    if age > timedelta(days=90):
        print(f"Key '{key['name']}' is {age.days} days old - consider rotating")

4. Use Expiring Keys

When creating keys in the dashboard, set an expiration date. This ensures keys automatically become invalid after a certain period.

5. Minimum Required Permissions

Only request the scopes you actually need when creating API keys.

Troubleshooting

Invalid API Key Error

from ashr_labs import AshrLabsClient, AuthenticationError

try:
    client = AshrLabsClient(api_key="invalid_key")
except ValueError as e:
    print(f"Invalid key format: {e}")

# If the key format is valid but the key itself is invalid:
try:
    datasets = client.list_datasets()
except AuthenticationError as e:
    print(f"Authentication failed: {e}")

Expired API Key

If your API key has expired, you'll receive an AuthenticationError:

from ashr_labs import AuthenticationError

try:
    datasets = client.list_datasets()
except AuthenticationError as e:
    if "expired" in str(e).lower():
        print("Your API key has expired. Please create a new one.")

Permission Denied

If you try to access an endpoint not allowed for API keys:

from ashr_labs import AuthorizationError

try:
    # This would fail - create_api_key requires OAuth
    # (Note: this method doesn't exist in the SDK for this reason)
    pass
except AuthorizationError as e:
    print(f"Permission denied: {e}")