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:
https://us.api.alpha.fastauth.dev/v1/authorize
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
0teams and1user 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
- Open the Dashboard in the Developer Console and click New Application.
- Give the application a name (for example,
Production APIorAI Refund Agent) and optionally pick a quickstart Cedar template (such as AI Agent Tool Guardrail or RBAC). - 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.
- Open your application → API Keys & Rotation tab and click Rotate on an existing key.
- Keep “Keep existing key active during rollout” checked (default) and click Generate Replacement Key.
- Deploy the new
sec_...secret to your backend services while both keys remain valid simultaneously. - Watch the old key’s
Last UsedUTC timestamp stop advancing, toggle it to Inactive (requests with that key immediately return401), 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/forbidrules are required; policy templates using?principalor?resourceslots return422(unsupported_template). - Empty policies are allowed: Saving an empty or comments-only policy succeeds (useful for testing default-deny behavior).
permit(
principal == User::"alice",
action == Action::"edit",
resource
) when { principal.role == }; // missing right-hand value
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-Versionpinning: Callers pass that strict positive integer (1,2,3) in theX-Policy-Versionheader. If omitted, FastAuth evaluateslatest_version. Prefixed or invalid values (likev2or0) return400 invalid_policy_version; unknown version numbers return404 policy_version_not_foundand 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.
- 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). - 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). - Click Evaluate Authorization to inspect the ALLOW or DENY decision, engine latency (ms), evaluated
Policy version, and matched Cedar rule@id(...)reasons.
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.
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": []
}
]
}'
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)
- Create Teams: Go to Organization & Profile → Teams and click Create Team (for example,
Core TeamandPayments Teamon Pro). - 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.
- 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 TeamandPayments Team). - 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.
- Clean Revocation: Removing a Member from a team — or deleting a team entirely — immediately revokes access to every application linked only through that team.
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).