Authentication

Every call is authenticated with a company API key and scoped to that key’s company. There is no per-user token on this surface: anything the key can see, the whole key can see.

Calling the REST API directly? The key goes in an Authorization: Bearer header — see any operation in the API reference.

Minting a key

In the Aura web app: Company settings → API keys → New key — minting and revoking are company-admin actions; any member can see the key list. The key is shown once, at creation — sk-aura-…. Store it somewhere your code can read it and treat it like a password.

Server-side only

A key grants access to every project in your company. Keep it out of browser bundles, shared logs, screenshots, and commits. If one leaks, revoke it in the same settings page and mint a replacement.

Passing it to a client

The two SDKs read nothing from the environment — the key is always explicit at the call site, so a library can never pick up an ambient credential you did not mean to use. The CLI is the opposite: it is a terminal tool, so it reads the environment by design.

TypeScript

import { AuraClient } from "@strangeworks/aura-sdk";

const aura = new AuraClient({ apiKey: process.env.AURA_API_KEY! });

Python

import os
from aura_sdk import AuraClient

async with AuraClient(api_key=os.environ["AURA_API_KEY"]) as aura:
    ...

CLI

export AURA_API_KEY="sk-aura-..."
aura project list

# or per invocation
aura project list --api-key "sk-aura-..."

What a rejected key looks like

An unusable key comes back as an API error carrying the HTTP status, not a special type — 401 for a key that is missing, malformed, or revoked, and 403 for a key that is valid but not entitled to the thing you asked for.

TypeScript

import { AuraApiError } from "@strangeworks/aura-sdk";

try {
  await aura.listProjects();
} catch (err) {
  if (err instanceof AuraApiError && err.status === 401) {
    throw new Error("AURA_API_KEY is missing or revoked");
  }
  throw err;
}

Python

from aura_sdk import AuraApiError

try:
    await aura.list_projects()
except AuraApiError as err:
    if err.status == 401:
        raise RuntimeError("AURA_API_KEY is missing or revoked") from err
    raise

Errors covers the rest, including the two error types that are about a turn rather than a request.