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 web interface (for security reasons):

1. Log in to the Ashr Labs web app
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

import { AshrLabsClient } from "ashr-labs";

// Only need API key — baseUrl defaults to production
const client = new AshrLabsClient("tp_your_api_key_here");

Environment Variables (Recommended)

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

export ASHR_LABS_API_KEY="tp_your_api_key_here"

import { AshrLabsClient } from "ashr-labs";

// Reads ASHR_LABS_API_KEY (required) and ASHR_LABS_BASE_URL (optional)
const client = AshrLabsClient.fromEnv();

Configuration File

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

# .env (DO NOT COMMIT)
ASHR_LABS_API_KEY=tp_your_api_key_here

import { AshrLabsClient } from "ashr-labs";
import "dotenv/config"; // or use your preferred env loader

const client = AshrLabsClient.fromEnv();

API Key Permissions

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

Operation	API Key Access
getDataset	Yes
listDatasets	Yes
createRun	Yes
getRun	Yes
listRuns	Yes
deleteRun	Yes
createRequest	Yes
getRequest	Yes
listRequests	Yes
listApiKeys	Yes
revokeApiKey	Yes
createApiKey	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

const apiKeys = await client.listApiKeys();
for (const key of apiKeys) {
  console.log(`Key: ${key.key_prefix}... | Name: ${key.name}`);
  console.log(`  Created: ${key.created_at}`);
  console.log(`  Last used: ${key.last_used_at ?? "Never"}`);
  console.log(`  Active: ${key.is_active}`);
}

Revoke an API Key

// Revoke a specific API key
await client.revokeApiKey(123);
console.log("API key revoked successfully");

Include Inactive Keys

// List all keys, including revoked ones
const allKeys = await client.listApiKeys(true);

Security Best Practices

1. Never Commit API Keys

Add to your .gitignore:

# API keys and secrets
.env
.env.local
*_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: npx tsx run_tests.ts

3. Rotate Keys Regularly

Create new keys periodically and revoke old ones:

const apiKeys = await client.listApiKeys();
for (const key of apiKeys) {
  const created = new Date(key.created_at as string);
  const ageMs = Date.now() - created.getTime();
  const ageDays = Math.floor(ageMs / (1000 * 60 * 60 * 24));

  if (ageDays > 90) {
    console.log(`Key '${key.name}' is ${ageDays} days old - consider rotating`);
  }
}

4. Use Expiring Keys

When creating keys in the web interface, 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

import { AshrLabsClient, AuthenticationError } from "ashr-labs";

try {
  const client = new AshrLabsClient("invalid_key");
} catch (e) {
  console.log(`Invalid key format: ${e}`);
}

// If the key format is valid but the key itself is invalid:
try {
  const datasets = await client.listDatasets();
} catch (e) {
  if (e instanceof AuthenticationError) {
    console.log(`Authentication failed: ${e.message}`);
  }
}

Expired API Key

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

import { AuthenticationError } from "ashr-labs";

try {
  const datasets = await client.listDatasets();
} catch (e) {
  if (e instanceof AuthenticationError && e.message.toLowerCase().includes("expired")) {
    console.log("Your API key has expired. Please create a new one.");
  }
}

Permission Denied

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

import { AuthorizationError } from "ashr-labs";

try {
  // Attempting a restricted operation
} catch (e) {
  if (e instanceof AuthorizationError) {
    console.log(`Permission denied: ${e.message}`);
  }
}