Skip to content

Authentication

API keys, their scopes and the Authorization header.

Every request to a route that needs a key sends the key in the Authorization header.

curl

curl https://api.albastov.com/v1/models \
  -H "Authorization: Bearer $ALBASTAR_API_KEY"

Python

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.albastov.com/v1",
    api_key=os.environ["ALBASTAR_API_KEY"],
)
print([m.id for m in client.models.list().data])

JavaScript

const res = await fetch("https://api.albastov.com/v1/models", {
  headers: { Authorization: `Bearer ${process.env.ALBASTAR_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
console.log((await res.json()).data.map((m) => m.id));
  • The scheme name Bearer is case-insensitive.
  • A key in a query string or a cookie is ignored.
  • The OpenAI SDKs send the header from api_key.
  • The docs, status and samples routes and GET /v1/events/docs need no key.

Keys

An account key starts with abk_, acts as one albastov.com account and opens the routes of its scopes. One key with llm and media:generate opens the language model and audio routes on one base URL.

ScopeOpens
llmGET /v1/models, POST /v1/chat/completions
media:readGET /v1/media/models, GET /v1/media/jobs/{id}, GET /v1/media/voices and the other voice GET routes
media:generatePOST /v1/audio/speech, POST /v1/audio/transcriptions, POST /v1/media/jobs, POST /v1/media/uploads, voice writes
events:publishPublishing events into the one source the key is bound to, PATCH /v1/events/sources/self and GET /v1/events/info
events:readListing events and sources, streaming and dismissing events of the key's sources, and GET /v1/events/info

media:generate does not include media:read: a program that saves a voice and lists voices needs both. The media: scopes also need an account with access to media; any other account fails with 403 account_cannot. Keys with events:publish or events:read are issued by Albastar Corp.; the same scope on any other account's key fails with 403 account_cannot. Each key has its own call limits (Rate limits).

LLM keys (hlk_) issued before account keys still work on GET /v1/models and POST /v1/chat/completions. New keys are account keys (abk_).

Getting a key

  • Albastar Corp. issues keys to an albastov.com account, with a name, scopes and call limits. An account cannot create its own key: write to Albastar Corp. at [email protected] with the account's address and the products the key is for.
  • A key is shown once, at creation. Store the key in a secret manager or an environment variable such as ALBASTAR_API_KEY.
  • Use one key per person or program.
  • Keep keys out of browser bundles, mobile apps, repositories and logs.

Revoked keys

A revoked key fails at once with 401. For a leaked key, ask Albastar Corp. for a new key and the revocation of the leaked one. Key errors per route: Errors.