Authentication

Authentication is configured as oke({ gate: { auth } }). That bag issues /auth/* Flows (unless http: false), fills fx.auth, and leaves permission to policy gates — there is no gate.auth handle for .gate(...).

For developers shipping signed-in APIs on okengine — turn on auth, plug a method, attach policies.

Smallest Example

import { oke } from "okengine";
import { username } from "okengine/plugins";

export const app = oke({
  name: "notes",
  env: "dev",
  gate: {
    auth: {
      // secret required in prod; minted in dev when omitted
      // basePath defaults to "/auth"
    },
  },
}).plug(username());

import { gate } from "okengine";

export const member = gate.policy("member", {
  description: "Signed-in user",
  check: ({ auth }) => !!auth.verified,
});

import { on, flow, http } from "okengine";
import { member } from "@/core/gate";

export const get = on(
  http.get().gate(member),
  flow({
    do: async (_, fx) => ({ userId: fx.auth.userId }),
  }),
);

# Method routes live under basePath (default /auth) — see your plugged method docs
curl -X GET http://localhost:6530/profile \
  -H "accept: application/json" \
  -H "authorization: Bearer …"

Progressive Patterns

From Bearer-only identity to cookies, API keys, and method plugins:

export const app = oke({
  name: "notes",
  env: "dev",
  gate: { auth: {} },
});

Options

What fx.auth carries

Inside do, read identity from fx.auth — not fx.user. World access stays on fx.

Sessions & Cookies

export const app = oke({
  name: "notes",
  env: "prod",
  gate: {
    auth: {
      secret: process.env.OKE_AUTH_SECRET!,
      session: {
        accessTtlMs: 14 * 60 * 1000,
        refreshTtlMs: 30 * 24 * 60 * 60 * 1000,
        freshAgeMs: 24 * 60 * 60 * 1000,
        // idleTtlMs / absoluteTtlMs / singleSessionPerUser when needed
      },
      cookies: {
        enabled: true,
        prefix: "oke",
        sameSite: "lax",
        secure: true,
        path: "/",
      },
    },
  },
});

Freshness: policies that require a recent sign-in should compare session age against session.freshAgeMs (default 24h). Step-up plugins (e.g. two-factor) build on the same window.

API Keys

{
  "data": null,
  "error": {
    "code": "Forbidden",
    "message": "You are not allowed to perform this action.",
    "data": { "gate": "auth:api-keys", "reason": "session_only" }
  }
}

Public routes

Health checks and login endpoints must declare open posture explicitly:

http.get().public();
// equivalent: http.get().gate(gate.public)

Auth method Flows under basePath register their own posture; your app routes still need .gate(...) or .public().

Set gate.auth.http: false when you want tables + Bearer verify without materializing /auth/* HTTP bindings (embedding / Console-style hosts).

Troubleshooting

Learn more

• Username plugin — email-free sign-up on gate.auth
• Authorization — scopes and ABAC policies
• RLS — row policies from stamped identity
• Tenancy — fx.tenant.id
• HTTP — .gate / .public on triggers

Next