Alpha Docs

FastAuth Documentation

Ship enterprise-grade AWS Cedar v4.12 authorization for your apps, SaaS platforms, and AI agents in minutes — without running policy servers, wrestling with IAM boilerplate, or risking broken rules in production. FastAuth combines sub-millisecond deterministic decisions, save-time syntax validation, immutable policy versioning, zero-downtime key rotation, an interactive Playground, and team-scoped access control in one developer-first platform.

1. Overview & Endpoints

FastAuth splits authorization into two clean surfaces: the Developer Console for managing organizations, teams, applications, keys, and Cedar policies, and the high-throughput Authorization Engine for evaluating live POST /v1/authorize requests. Every snippet on this page is pre-configured for the Alpha environment:

Authorization Engine Endpoint
https://us.api.alpha.fastauth.dev/v1/authorize
Developer Console
https://console.alpha.fastauth.dev

2. Free Organization Account

FastAuth separates human identity from organization tenancy. The first time you sign into the Developer Console, FastAuth automatically provisions one Free Organization for your account.

  • Single-User Owner: You are assigned the Owner role with full administrative permissions across every application in your organization.
  • No Teams Required: Free organizations have 0 teams and 1 user seat — you can immediately create apps, edit Cedar policies, rotate API keys, and run evaluations without any team setup.
  • Generous Free Quotas: Up to 10 applications and 10,000 metered requests/month (hard cap; Playground tests do not count toward quota).
  • In-Place Growth: You never have to migrate data or recreate apps when growing — rename your organization and upgrade from Organization & Profile → Plan with zero downtime.

3. Applications & Zero-Downtime Key Rotation

Create an Application

  1. Open the Dashboard in the Developer Console and click New Application.
  2. Give the application a name (for example, Production API or AI Refund Agent) and optionally pick a quickstart Cedar template (such as AI Agent Tool Guardrail or RBAC).
  3. Copy the generated API Secret (sec_...) and Application ID (X-Client-ID). FastAuth shows the plaintext secret exactly once and stores only its SHA-256 hash — zero secret characters are ever displayed again.

Rotate API Keys Without Downtime

Each application supports up to 5 API keys with real-time UTC last_used_at tracking and independent Active / Inactive toggles.

  1. Open your application → API Keys & Rotation tab and click Rotate on an existing key.
  2. Keep “Keep existing key active during rollout” checked (default) and click Generate Replacement Key.
  3. Deploy the new sec_... secret to your backend services while both keys remain valid simultaneously.
  4. Watch the old key’s Last Used UTC timestamp stop advancing, toggle it to Inactive (requests with that key immediately return 401), and permanently Delete it once verified.

4. Cedar Policies, Save-Time Validation & Versioning

FastAuth evaluates policies using the Native AWS Cedar v4.12 model: principal, action, and resource are strict Entity UIDs, while attributes (attrs) and hierarchies (parents) live in the top-level entities array alongside runtime context.

Save-Time Syntax Validation & Error Diagnostics

Every time you click Save Policy (or call PUT /policy), FastAuth parses the policy with Cedar before writing to Cloud Storage or advancing your version. Broken syntax never overwrites a working production policy.

  • Syntax errors rejected inline: Missing semicolons, unclosed strings, or invalid conditions return HTTP 422 (invalid_cedar_syntax) and display an inline Cedar Policy Validation Failed banner above the editor.
  • Unlinked template slots rejected: Static permit/forbid rules are required; policy templates using ?principal or ?resource slots return 422 (unsupported_template).
  • Empty policies are allowed: Saving an empty or comments-only policy succeeds (useful for testing default-deny behavior).
Example invalid policy (rejected on save):
permit(
  principal == User::"alice",
  action == Action::"edit",
  resource
) when { principal.role == };   // missing right-hand value
422 Cedar Policy Validation Failed (invalid_cedar_syntax):
Invalid Cedar policy syntax: unexpected token `}`
Your previous saved version remains completely untouched and continues serving live traffic.

Immutable Policy Versioning & History

  • Monotonic immutable versions: Each validated save creates a new immutable integer version (1, 2, 3…). Re-saving byte-identical text is a no-op and does not create a duplicate version.
  • X-Policy-Version pinning: Callers pass that strict positive integer (1, 2, 3) in the X-Policy-Version header. If omitted, FastAuth evaluates latest_version. Prefixed or invalid values (like v2 or 0) return 400 invalid_policy_version; unknown version numbers return 404 policy_version_not_found and never silently fall back or consume quota.
  • Version History & Copy-Forward Restore: Below the Cedar editor, Policy Version History displays every version’s author, UTC timestamp, optional change note, and 90-day metered invocation count. Click View to inspect an earlier policy, Test to open it in the Playground, or Restore to publish a new latest version copied from that historical snapshot without mutating older versions.

5. Testing in the Interactive Playground

Open any application and switch to the Interactive Playground tab to validate rules in real time against live Cedar v4.12 evaluation before deploying your code.

  1. Choose the target Policy Version in the top-right selector (defaults to the latest saved version, e.g. version 3, or pick any earlier version to compare behavior).
  2. Enter Principal (Type + ID), Action, and Resource (Type + ID), plus optional Context JSON and Entities JSON array — or click a one-click preset like AI Agent (Entities + Context).
  3. Click Evaluate Authorization to inspect the ALLOW or DENY decision, engine latency (ms), evaluated Policy version, and matched Cedar rule @id(...) reasons.
Unmetered Testing: Playground requests authenticate with your Console session token plus X-Client-ID and are excluded from monthly quota and per-version metered usage counts.

6. API Integration (cURL, Python, Node.js / TypeScript)

Evaluate authorization from any backend service or AI agent runtime by sending an HTTPS POST request to https://us.api.alpha.fastauth.dev/v1/authorize.

Deterministic Production Calls: Every saved policy receives an immutable positive integer version (1, 2, 3…). We strongly recommend passing X-Policy-Version: <int> on every POST /v1/authorize request for predictable, deterministic behavior even while teammates iterate on newer policy versions.
Header Required Description
Authorization Yes Bearer sec_<your_secret> (or pass the secret via X-API-Key).
X-Client-ID Yes Your FastAuth Application ID (required on every authorization call).
X-Policy-Version Recommended Strict positive integer (1, 2, 3). Pins evaluation to an immutable version; omits to use latest_version.
Content-Type Yes application/json

cURL

curl -X POST https://us.api.alpha.fastauth.dev/v1/authorize \
  -H "Authorization: Bearer <YOUR_APPLICATION_SECRET>" \
  -H "X-Client-ID: <YOUR_APPLICATION_ID>" \
  -H "X-Policy-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": "Agent::\"support_bot\"",
    "action": "Action::\"invoke_tool\"",
    "resource": "Tool::\"stripe_refund\"",
    "context": {
      "refund_amount": 45,
      "human_approved": false
    },
    "entities": [
      {
        "uid": {"type": "Agent", "id": "support_bot"},
        "attrs": {"autonomy": "autonomous", "max_refund_limit": 100},
        "parents": [{"type": "Role", "id": "SupportTier1"}]
      },
      {
        "uid": {"type": "Tool", "id": "stripe_refund"},
        "attrs": {"environment": "production", "sensitivity": "financial"},
        "parents": []
      }
    ]
  }'
Sample 200 OK response:
{
  "decision": "Allow",
  "reasons": ["allow_support_agent_bounded_refund"],
  "errors": [],
  "evaluationTimeMs": 0.42,
  "entitiesEvaluatedCount": 2,
  "requestId": "req_9f2c1a4b8d10",
  "applicationId": "app_1234567890ab",
  "policyVersion": 1
}

Python (requests)

import os
import requests

FASTAUTH_AUTHZ_URL = "https://us.api.alpha.fastauth.dev/v1/authorize"
FASTAUTH_CLIENT_ID = os.environ["FASTAUTH_CLIENT_ID"]
FASTAUTH_API_SECRET = os.environ["FASTAUTH_API_SECRET"]
FASTAUTH_POLICY_VERSION = "1"  # Pin to a strict positive integer for deterministic behavior


def is_allowed(
    principal: str,
    action: str,
    resource: str,
    *,
    entities: list[dict] | None = None,
    context: dict | None = None,
    policy_version: str = FASTAUTH_POLICY_VERSION,
) -> bool:
    response = requests.post(
        FASTAUTH_AUTHZ_URL,
        headers={
            "Authorization": f"Bearer {FASTAUTH_API_SECRET}",
            "X-Client-ID": FASTAUTH_CLIENT_ID,
            "X-Policy-Version": str(policy_version),
            "Content-Type": "application/json",
        },
        json={
            "principal": principal,
            "action": action,
            "resource": resource,
            "entities": entities or [],
            "context": context or {},
        },
        timeout=5,
    )
    response.raise_for_status()
    data = response.json()
    return data["decision"] == "Allow"


allowed = is_allowed(
    'User::"alice"',
    'Action::"edit"',
    'Document::"doc_101"',
    entities=[
        {
            "uid": {"type": "User", "id": "alice"},
            "attrs": {"role": "Editor"},
            "parents": [],
        }
    ],
)
print("Authorized:", allowed)

Node.js / TypeScript (native fetch)

interface CedarEntity {
  uid: { type: string; id: string };
  attrs?: Record<string, unknown>;
  parents?: Array<{ type: string; id: string }>;
}

interface AuthorizeRequest {
  principal: string;
  action: string;
  resource: string;
  entities?: CedarEntity[];
  context?: Record<string, unknown>;
}

interface AuthorizeResponse {
  decision: "Allow" | "Deny";
  reasons: string[];
  errors: string[];
  evaluationTimeMs: number;
  entitiesEvaluatedCount: number;
  requestId: string;
  applicationId: string;
  policyVersion: number | null;
}

const FASTAUTH_AUTHZ_URL = "https://us.api.alpha.fastauth.dev/v1/authorize";

export async function authorize(
  payload: AuthorizeRequest,
  policyVersion = 1
): Promise<AuthorizeResponse> {
  const res = await fetch(FASTAUTH_AUTHZ_URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.FASTAUTH_API_SECRET}`,
      "X-Client-ID": process.env.FASTAUTH_CLIENT_ID ?? "",
      "X-Policy-Version": String(policyVersion),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      entities: [],
      context: {},
      ...payload,
    }),
  });

  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(`FastAuth error (${res.status}): ${err.message ?? res.statusText}`);
  }
  return (await res.json()) as AuthorizeResponse;
}

// Example usage (Node 18+ / TypeScript)
const result = await authorize(
  {
    principal: 'User::"alice"',
    action: 'Action::"edit"',
    resource: 'Document::"doc_101"',
    entities: [
      {
        uid: { type: "User", id: "alice" },
        attrs: { role: "Editor" },
        parents: [],
      },
    ],
  },
  1
);

if (result.decision !== "Allow") {
  throw new Error(`Forbidden (policy version ${result.policyVersion})`);
}

Common API Status Codes

HTTP Code Meaning
400 invalid_policy_version Missing/invalid X-Client-ID, malformed JSON, or non-integer X-Policy-Version (e.g. v2 or 0).
401 — Missing, inactive, deleted, or mismatched API secret.
404 policy_version_not_found The requested X-Policy-Version does not exist on this application (unmetered).
422 — Invalid Native Cedar payload (for example, missing principal/action/resource or inline principal attribute bags).
429 quota_exceeded Organization monthly request cap reached.

7. Teams & Multi-User Access (Starter, Pro & Enterprise)

FastAuth uses a strict GitHub-style separation between Organization Roles (Owner vs. Member) and Teams. Teams unlock on Starter (1 team, up to 5 users) and expand on Pro (5 teams, up to 25 users) and Enterprise (50+ teams, 100+ users).

Owner Full Organization Control

Owners (and promoted Co-owners) automatically access all applications in the organization, create/delete apps, manage teams and memberships, assign teams to apps, and manage plan upgrades. The last Owner cannot be demoted or removed (409 last_owner_required).

Member Explicit Team-Scoped Access

Members join Unassigned (0 teams → 0 applications visible by default). A Member can only access applications assigned to at least one of their teams, and cannot view org-wide Teams, Member rosters, or seat counters.

Step-by-Step Team Workflow (Pro Multi-Team Example)

  1. Create Teams: Go to Organization & Profile → Teams and click Create Team (for example, Core Team and Payments Team on Pro).
  2. Invite Teammates by Email: Under Organization & Profile → Members, click Invite Teammate and enter their email address. Their display name populates automatically when they sign in. Until assigned to a team, they remain Unassigned with zero app access.
  3. Assign Members to Teams: Click Assign Teams on any Member row and select one or more teams. One person can belong to multiple teams (for example, both Core Team and Payments Team).
  4. Assign Teams to Applications: Create an application or click Manage Access on an existing app to select which teams can access it. One team can be assigned to multiple applications, and an application can be shared across multiple teams. Applications with no teams assigned remain strictly Owner-only.
  5. Clean Revocation: Removing a Member from a team — or deleting a team entirely — immediately revokes access to every application linked only through that team.
Zero Implicit Access: Inviting a teammate never grants access to existing applications automatically. You must both assign the Member → Team and assign the Team → Application(s) (or explicitly promote the Member to Co-owner).

8. Plans, Quotas & Support Cases

Plan Requests / Month Applications Users Teams Support
Free ($0) 10,000 (hard cap) 10 1 (Owner) 0 Community & Docs
Starter ($29/mo) 200,000 20 5 1 In-console support cases
Pro ($99/mo) 1,000,000 100 25 5 Priority support cases
Enterprise ($299/mo+) 10,000,000+ 1,000+ 100+ 50+ Dedicated support cases & 99.99% SLA

Usage & Metering: Organization usage charts under Organization & Profile display aggregated monthly and daily totals per application (90-day retention). Per-version invocation counts live inside each application’s Policy Version History.

In-Console Support Cases: Organizations on Starter, Pro, or Enterprise can open, track, and resolve support cases directly under Support in the Developer Console (Open, Awaiting Customer, Resolved).