Authentication & API keys

How your API key becomes a JWT, how the SDK refreshes it, and where to store secrets in dev and prod.

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)

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.

Bring your own JWT

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.

Org + user login (debug only)

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

1. Mint key B

   Dashboard → API Keys → New key.

2. Roll out

   Deploy with TEX_API_KEY=<key B>.

3. Verify

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

4. 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

Python

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

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.