reference · auth

Authentication

Every OriginChain API call is authenticated with a bearer token in the Authorization header. There are no API keys, no signed-request schemes, no OAuth dance. One header, one token, every call.

1. Get a token.

Tokens are created in the dashboard. Open app.originchain.ai → your instance → API tokens → Create token.

The token is shown once at creation - never again. Paste it into your secrets manager before closing the page.
The token starts with oc_live_ (production) or oc_test_ (trial instances).
Tokens are scoped to a single instance. Multiple instances need multiple tokens.
You can create as many tokens as you like. Name them by use case ("github-actions", "etl-pipeline", "laptop-debug") so revoking the right one is easy.

2. Use the token.

Set it in your shell, then attach it to every API call. The SDKs read it once at client construction and reuse it for the lifetime of the client.

bearer token usage

# Every API call includes one header:
curl "https://$OC_HOST/v1/tenants/$OC_TENANT/schemas" \
  -H "Authorization: Bearer $OC_TOKEN"

from originchain import OriginChain

db = OriginChain(
    base_url=os.environ["OC_BASE_URL"],
    bearer=os.environ["OC_BEARER"],
    tenant=os.environ["OC_TENANT"],
)

import { OriginChainClient } from "@originchain/sdk";

const db = new OriginChainClient({
  baseUrl: process.env.OC_BASE_URL!,
  bearer:  process.env.OC_BEARER!,
});

db := originchain.NewClient(originchain.Config{
    BaseURL: os.Getenv("OC_BASE_URL"),
    Bearer:  os.Getenv("OC_BEARER"),
})

what happens when auth fails

Status	Cause
401 unauthorized	No `Authorization` header, malformed header, or the token doesn't match any known token for the instance.
403 forbidden	Token is valid but targets a different instance. Check the endpoint hostname matches the token's instance.
404 instance not found	The endpoint URL is wrong, or the instance was deleted.

3. Storing tokens safely.

A bearer token grants full access to the instance it was created for. Treat it like a password.

Store tokens in a secrets manager (1Password, AWS Secrets Manager, GCP Secret Manager, Doppler, Infisical).
Load them into apps via environment variables.
Create one token per use case so revoking is targeted.
Use short-lived tokens for CI/CD - rotate them on a schedule.

don't

Commit tokens to git, even in private repos.
Send tokens to client-side code (browsers, mobile apps). They're full-access; anyone who inspects the JS sees the token.
Share tokens via Slack, email, or screenshots.
Put tokens in URLs - they end up in proxy logs, browser history, and shell history.

4. Rotation.

Rotate tokens regularly even if nothing has gone wrong. The pattern is overlap, then revoke:

Create a new token in the dashboard.
Update your secret manager / env var with the new token.
Restart your app, or wait for the rolling deploy to pick it up.
Confirm requests are still landing (check the dashboard's recent activity panel).
Revoke the old token in the dashboard.

Revocation is immediate. After you revoke a token, every request using it returns 401 within a few seconds.

5. If a token leaks.

If you suspect a token was exposed (committed to a public repo, posted in a chat, found in a log file someone else can read):

Revoke the token immediately in the dashboard. This is the only action that matters.
Check the instance's activity panel for any requests you didn't make.
Create a new token and update your apps.
If the leak was a public repo, also scrub the git history - the old commits still contain the token even if you delete the file.

If you discover suspicious activity, email security@originchain.ai. We'll help you scope the exposure and check our logs.