Authentication & API keys

If you only need a working client, start with the Quickstart. Come back here when you are wiring secrets, using your own JWT, or rotating keys.

The SDK starts with your API key. On the first real call, it exchanges that key for short-lived access and refresh tokens. After that, the client keeps the tokens in memory, refreshes them when needed, and retries the original call. Most apps never need to handle raw token strings.

Flow

The diagram shows what happens when your app calls the SDK.

Steps in the SDK

Auth mode

Most apps use an API key. Use one of the other modes only when you already manage auth somewhere else.

API key (recommended)
Bring your own JWT
Org + user login (debug only)

tex = Tex(
    api_key="tex_live_…",
    base_url="https://api.getmetacognition.com",
)

This is the default for most apps. The SDK handles token exchange and refresh.

tex = Tex(
    access_token=jwt_from_my_auth_service,
    refresh_token=refresh_jwt,           # optional
    org_id="org_abc",                    # required with BYO-JWT
    user_id="u_xyz",                     # required with BYO-JWT
    base_url="https://api.getmetacognition.com",
)

Use this when another service already creates the JWTs.

BYO-JWT does not auto-fill org_id / user_id from /auth/verify. Pass them explicitly. Every remember and recall needs them in the request scope.

tex = Tex(
    org_id="org_abc",
    user_id="u_xyz",
    base_url="http://localhost:8000",
)

/auth/login is disabled in production. It returns 403 unless the integration backend runs with DEBUG=true. Use this only for local development against a self-hosted backend. In production, use an API key.

Key storage

Local dev

.env file. Add it to .gitignore. Load with python-dotenv.

Docker / Kubernetes

Secret manager mounted as TEX_API_KEY env var.

Vercel / Netlify

Project environment variable named TEX_API_KEY.

GitHub Actions

Repository secret exposed as ${{ secrets.TEX_API_KEY }}.

The SDK reads TEX_API_KEY from the environment automatically when api_key= is omitted.

Rotation

Mint key B

Dashboard → API Keys → New key.

Roll out

Deploy with TEX_API_KEY=<key B>.

Verify

Check the dashboard’s last_used_at value or your own logs.

Revoke key A

Click Revoke on the old key. JWTs created from key A can keep working for up to 24h, so customers do not see a sudden failure.

Bad key

from tex import Tex, AuthenticationError

try:
    tex = Tex(api_key="tex_live_BOGUS", base_url="https://api.getmetacognition.com")
    tex.usage.today()
except AuthenticationError as e:
    print(e.status_code)   # 401
    print(e.message)       # "Invalid API key" or similar
    print(e.request_id)    # Quote this when filing tickets

$ curl -X POST https://api.getmetacognition.com/auth/token-exchange \
    -H 'content-type: application/json' \
    -d '{"api_key": "tex_live_BOGUS"}'

{"error":"HTTP 401","message":"Invalid API key","request_id":"…"}

Token lifetimes. Access JWTs last 24h. Refresh JWTs last 7d. After that, the SDK exchanges your API key again. To invalidate tokens, revoke the API key they came from.

Next: multi-user memory

How org_id / user_id / session_id partition memory.

Get started

Concepts

Cookbook

Evaluation

Migration

Support

Flow

Steps in the SDK

Auth mode

Key storage

Local dev

Docker / Kubernetes

Vercel / Netlify

GitHub Actions

Rotation

Bad key

Next: multi-user memory

​Flow

​Steps in the SDK

​Auth mode

​Key storage

Local dev

Docker / Kubernetes

Vercel / Netlify

GitHub Actions

​Rotation

​Bad key

Next: multi-user memory

Flow

Steps in the SDK

Auth mode

Key storage

Rotation

Bad key