LiquidMetal AI: how do I set up JWT/OAuth, RBAC, and API keys for a public API?

Quick Answer: In Raindrop, you don’t bolt on JWT/OAuth, RBAC, and API keys after the fact—you declare them once in your manifest and ship a production-ready public API with built-in auth, access control, and key management. You define who can call what, how they authenticate (JWT, OAuth, or API key), and what limits apply, then Raindrop enforces it globally with full logging and versioning.

Why This Matters

When you expose a public API, the hard part isn’t generating responses—it’s securing them. If you’re stitching together your own JWT service, OAuth provider, key store, and rate limiting, you’re spending weeks on glue work and still hoping nothing leaks. Raindrop turns authentication, RBAC, and API keys into first-class, versioned config so you can ship a monetizable, auditable API from day one.

Key Benefits:

• Security built in, not bolted on: JWT, OAuth, RBAC, and API keys are core runtime features, not custom middleware you have to maintain.
• Production governance from day one: Every request is authenticated, authorized, logged, and tied to a version of your code, data, and smart primitives.
• Faster time-to-revenue: Tiered plans, usage tracking, and automatic rate limiting mean you can safely charge for public API access without extra billing infra.

Core Concepts & Key Points

Concept	Definition	Why it's important
JWT/OAuth Auth	Built-in authentication layer supporting JWT tokens, OAuth integration, and API key validation for every Raindrop service.	Gives you enterprise-grade auth without running an auth service, and standardizes how clients sign and verify calls.
RBAC (Role-Based Access Control)	Fine-grained permissions attached to users, API keys, or OAuth clients that control access to specific routes or operations.	Lets you expose a public API safely by separating free/paid/admin capabilities and preventing cross-tenant data access.
API Keys & Billing Tiers	Managed keys tied to plans with usage tracking and automatic rate limiting per tier.	Converts your public API into a product: you can throttle abuse, cap usage, and bill based on actual consumption.

How It Works (Step-by-Step)

At a high level, you define a public Raindrop service in a manifest, declare your auth methods and RBAC rules, and let the runtime enforce everything for each request.

1. Declare a public service with auth in your manifest:

   • Mark the service as visibility = "public".
   • Configure allowed auth methods (JWT, OAuth, API keys).
   • Attach roles and scopes to routes or operations.

2. Configure JWT/OAuth providers and roles:

   • Register JWT issuers or OAuth clients (e.g., your IdP or app).
   • Define roles (e.g., free, pro, admin) and attach them to plans or clients.
   • Map roles to route-level permissions.

3. Issue API keys and connect them to billing tiers:

   • Create API keys per user/tenant and assign them to a tier.
   • Use built-in monetization: tiered plans, usage-based billing, rate limiting.
   • Raindrop tracks usage per key and enforces limits automatically.

From the client’s perspective, hitting your public API is just:

• Bearer token (JWT or OAuth access token), or
• API key (e.g., in header)

From your perspective, you get:

• Auth validation
• RBAC checks
• Rate limiting and billing
• Full observability of every AI decision and smart-primitive call

…without needing separate services.

---

Step 1: Declare a Public API in Raindrop

In Raindrop, every backend is defined declaratively. Think of it as “API as config” plus intelligence primitives.

A public API starts as a service block in your manifest:

service "public-api" {
  visibility = "public"

  domain {
    fqdn = "api.<YOUR ORG ID>.liquidmetal.run"
  }

  // Example route (high level, pseudo-structure)
  routes {
    path   = "/v1/analyze"
    method = "POST"

    // attach auth and RBAC policy here
    auth  = "jwt_or_api_key"
    roles = ["free", "pro", "admin"]
  }
}

Key points:

• visibility = "public" exposes the service on a globally routable domain.
• Raindrop handles TLS, routing, and scaling for you—no extra infra.
• The service can call SmartMemory, SmartBuckets, SmartSQL, and SmartInference behind the scenes; auth and RBAC still apply.

All of this is fully versioned: if you change the manifest, you can roll back/forward to any version of your public API, including its auth rules.

---

Step 2: Enable JWT & OAuth Authentication

You rarely want to operate an auth server just to ship a single API. Raindrop plugs into JWT and OAuth so you can rely on your identity provider or app.

2.1 Configure JWT validation

You typically:

• Provide the issuer (iss) and audience (aud) to trust.
• Point Raindrop at JWKS or public keys.
• Optionally map token claims to roles.

Conceptually (structure may differ slightly depending on CLI/template):

auth "jwt" {
  enabled  = true
  issuer   = "https://auth.mycompany.com/"
  audience = "my-public-api"

  // Map JWT claim -> roles
  role_claim = "roles"
}

At runtime:

• A client includes Authorization: Bearer <JWT>
• Raindrop validates signature, expiry, issuer, audience.
• Roles are derived from claims and checked against your RBAC rules.

You don’t write middleware; you declare policy.

2.2 Configure OAuth integration

For OAuth, Raindrop acts as the backend enforcement layer:

• You integrate with your OAuth provider for user consent and token issuance.
• Raindrop trusts the provider’s tokens and enforces scopes/roles on calls.

Example conceptually:

auth "oauth" {
  enabled = true

  provider "my-oauth" {
    issuer   = "https://accounts.example.com"
    audience = "my-public-api"
    scopes   = ["read", "write"]
  }
}

You can:

• Require specific scopes on a route (scopes = ["read"]).
• Combine with RBAC roles for fine-grained access.

---

Step 3: Define RBAC for Routes and Operations

JWT/OAuth are about identity. RBAC is about what that identity may do.

Raindrop’s role-based access control lets you:

• Define roles (e.g., anonymous, free, pro, admin).
• Attach roles to users, tenants, or API keys.
• Restrict individual endpoints or primitive operations.

Conceptual example:

rbac {
  roles = ["anonymous", "free", "pro", "admin"]

  policy "public-health" {
    route = "/v1/health"
    allow = ["anonymous"]
  }

  policy "analyze-free" {
    route = "/v1/analyze"
    method = "POST"
    allow = ["free", "pro", "admin"]
  }

  policy "admin-metrics" {
    route = "/v1/metrics"
    allow = ["admin"]
  }
}

Benefits:

• You can safely expose health and docs endpoints without auth.
• Free users can access core features with limits enforced via billing tiers.
• Admin-only routes are fully isolated, even if someone leaks an API key for a lower tier.

All access decisions are logged: who called what, under which role, and which version of your API and smart primitives processed the request.

---

Step 4: Issue API Keys and Connect Them to Billing

Not every client wants OAuth. For server-to-server and paid plans, API keys are the simplest path.

Raindrop gives you:

• API key management
• Tiered pricing plans
• Usage-based billing
• Automatic rate limiting per tier

So you can treat your API as a product from day one.

4.1 Create plans and tiers

Conceptually:

billing {
  plan "free" {
    rate_limit {
      requests_per_minute = 60
    }
  }

  plan "pro" {
    rate_limit {
      requests_per_minute = 600
    }
    usage_pricing {
      per_1k_requests = 0.50
    }
  }

  plan "enterprise" {
    rate_limit {
      requests_per_minute = 6000
    }
  }
}

Raindrop handles:

• Usage tracking (per API key, per plan).
• Rate limiting per tier (e.g., auto 429 when exceeded).
• Payment processing and billing logic.

4.2 Create and assign API keys

You use the CLI or dashboard to:

1. Create a key for a user or tenant.
2. Assign it a plan (free, pro, enterprise).
3. Optionally map it to roles (pro user with read/write).

Example client usage:

GET /v1/analyze HTTP/1.1
Host: api.<ORG ID>.liquidmetal.run
X-API-Key: sk_live_abcdef...

Under the hood, Raindrop:

• Authenticates the key.
• Resolves its plan and roles.
• Applies RBAC checks on the route.
• Enforces plan limits and usage accounting.

No separate key database or rate limiter required.

---

Common Mistakes to Avoid

• Treating “public” as “unauthenticated”:
  How to avoid it: Always pair visibility = "public" with explicit auth and RBAC policies. Use anonymous only where you truly want open access (e.g., docs).

• Mixing business logic with auth logic in code:
  How to avoid it: Keep auth, roles, and tiers in the manifest. Let Raindrop enforce auth and limits so your service code stays focused on using SmartInference, SmartMemory, or SmartBuckets.

---

Real-World Example

Say you’re shipping a “Generative Analytics API” that lets users run natural-language analytics over their own data using SmartSQL and SmartInference.

You want:

• Anyone to see docs and ping /v1/health.
• Free users to run small queries.
• Pro users to run larger workloads and more concurrent calls.
• Admins to inspect logs and stats.

In Raindrop, you:

1. Define a public analytics-api service with routes for /v1/query, /v1/health, /v1/admin/stats.
2. Enable JWT and API keys; configure RBAC so:
   • /v1/health → anonymous allowed.
   • /v1/query → free, pro, admin allowed.
   • /v1/admin/stats → only admin.
3. Create billing plans (free, pro) with different rate limits and pricing.
4. Issue API keys to each customer and assign them to free or pro plans.
5. Use SmartSQL inside your service to query their data and SmartInference to summarize results, with every AI decision and query logged for audits.

When a pro customer hits /v1/query with their key:

• Raindrop authenticates the key, resolves the pro plan and roles.
• RBAC checks pass.
• Rate limits + usage accounting run automatically.
• SmartSQL and SmartInference calls are executed with observability and versioning.

If you later discover a bug or misconfigured RBAC rule, you can roll back to a previous manifest version and know exactly what changed and why.

Pro Tip: Treat your auth and RBAC config like code: version it in Git alongside your Raindrop manifest, and rely on Raindrop’s complete versioning to roll back misconfigurations without touching your business logic.

---

Summary

Setting up JWT/OAuth, RBAC, and API keys for a public API on LiquidMetal AI’s Raindrop runtime is a declarative exercise, not an infrastructure project. You define a public service, enable built-in authentication, attach role-based policies to routes, and tie API keys to billing tiers—all fully versioned, observable, and globally scalable. The result is a production-grade, monetizable API where security, access control, and monetization are built in, not bolted on.

Next Step

Get Started