Authentication - Archyon

Every non-public endpoint requires a Bearer credential in the Authorization header. Two credential types are accepted; the server distinguishes them by token shape, so no scheme selection is required by the caller.

Authorization: Bearer <credential>

Credential	Audience	Lifetime
Clerk session JWT	Browser clients using the official Clerk SDK	Short (≤1 hour, auto-refreshed)
Archyon Personal Access Token (`an_pat_…`)	Scripts, CI jobs, and any other non-browser client	Until explicitly revoked
MCP access token (`an_mcp_…`)	Hosted MCP Connector — issued by the OAuth flow described under Connectors	~1 hour, auto-refreshed

The two endpoints exempt from authentication are POST /api/waitlist (public marketing form) and GET /api/auth/notion/callback (OAuth redirect, validated by state nonce).

Personal access tokens

Personal access tokens (PATs) are the right credential for scripts, CI jobs, and direct API access from outside a browser. For connecting Claude as an assistant, prefer the hosted Connector flow, which manages tokens automatically.

Format

an_pat_<random>

The an_pat_ prefix identifies the token type. The remainder is opaque to the client and must not be parsed. Server-side, only a SHA-256 hash of the token is stored — the plaintext value is unrecoverable after the response that mints it.

Creating a token

Sign in at archyon.app.
Use the organization switcher in the application header to activate the organization the token should act in.
Navigate to Account → Tokens.
Click New token and provide a descriptive name.
Copy the returned an_pat_… value immediately. It is displayed once.

Alternatively, mint a token programmatically from a session that already has a Clerk JWT:

curl -X POST https://archyon.app/api/me/tokens \
  -H "Authorization: Bearer <clerk_jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-deploy-pipeline"}'

{
  "token": "an_pat_…",
  "prefix": "an_pat_abc12",
  "name": "ci-deploy-pipeline",
  "orgId": "org_2abc...",
  "hint": "Active in the ACME organization."
}

Organization binding

A PAT is bound to whichever organization is active in the minting session, and the binding is permanent. Switching organizations in the application has no effect on existing tokens. To act in a different organization from a non-browser client, mint a new token while that organization is active. Tokens minted before the binding was introduced have a null orgId and can only call endpoints that operate at instance scope. These legacy tokens should be revoked and replaced. The application surfaces the bound organization in the token list and marks the currently-active organization in green.

Using a token

curl https://archyon.app/api/me \
  -H "Authorization: Bearer $ARCHYON_TOKEN"

const res = await fetch("https://archyon.app/api/me", {
  headers: {
    Authorization: `Bearer ${process.env.ARCHYON_TOKEN}`,
  },
});
const me = await res.json();

import os, requests

res = requests.get(
    "https://archyon.app/api/me",
    headers={"Authorization": f"Bearer {os.environ['ARCHYON_TOKEN']}"},
)
me = res.json()

The response confirms which organization the credential is acting in:

{
  "id": 42,
  "displayName": "Ada Lovelace",
  "isAdmin": false,
  "provider": "clerk",
  "createdAt": 1716566400000,
  "session": {
    "orgId": "org_2abc...",
    "orgRole": "org:admin",
    "orgSlug": "acme",
    "isApiToken": true
  }
}

Listing tokens

curl https://archyon.app/api/me/tokens \
  -H "Authorization: Bearer $ARCHYON_TOKEN"

The response includes the prefix, the bound organization, and the last-used timestamp for each token. Plaintext values are never returned.

Revoking a token

Revocation is immediate. Subsequent requests with the revoked token receive 401 Unauthorized.

curl -X DELETE https://archyon.app/api/me/tokens/<id> \
  -H "Authorization: Bearer $ARCHYON_TOKEN"

The token list in the application provides an equivalent Revoke action.

Security considerations

Treat PATs as passwords. Store them in a secret manager and never commit them to source control.
Issue separate tokens per client (one per CI pipeline, one per laptop, one per MCP installation). The cost of revoking a single compromised credential then equals the cost of re-minting one token.
Tokens are not scoped by permission today; a PAT inherits the full role of the user who minted it within the bound organization. Apply the principle of least privilege at the user level — mint tokens from accounts whose role matches the intended use.

Clerk session JWTs

Browser applications authenticate with short-lived JWTs minted by the Clerk SDK and attached to every request.

import { useAuth } from "@clerk/clerk-react";

function useArchyonFetch() {
  const { getToken } = useAuth();
  return async (path: string, init?: RequestInit) => {
    const jwt = await getToken();
    return fetch(`https://archyon.app${path}`, {
      ...init,
      headers: {
        ...(init?.headers ?? {}),
        Authorization: `Bearer ${jwt}`,
      },
    });
  };
}

For organization-scoped endpoints, the Clerk session template must include the org_id, org_role, and org_slug claims so that the API can derive organization context from the JWT. The hosted Archyon instance at archyon.app is configured correctly out of the box. Self-hosted deployments must configure the session template manually; see DEPLOYMENT.md in the repository.

No active organization

Resources scoped to an organization — workspaces, people, teams, stakeholder roles, the Notion integration — return 400 Bad Request with code: "no_active_org" when the caller’s session has no organization context:

{
  "error": "Active organization required to create or modify org-scoped entities.",
  "code": "no_active_org"
}

Resolution depends on the credential type:

Browser clients should prompt the user to select an organization in the Clerk organization switcher.
Personal access tokens must be re-minted while the desired organization is active in the application.

Instance superadministrators bypass this check on read endpoints to support cross-organization investigations, but write endpoints still require an explicit organization context.

​Personal access tokens

​Format

​Creating a token

​Organization binding

​Using a token

​Listing tokens

​Revoking a token

​Security considerations

​Clerk session JWTs

​No active organization