Index of every page on this site: llms.txt
All skills
encoredev avatar

/auth

@e86a3ab official
by Encoreencoredev/skills30 stars
6
Run it yourself

Protect Encore.ts endpoints with authentication and authorize callers. Covers `authHandler`, `Gateway`, `getAuthData`, and `auth: true`.

  • 1 file
  • 6.9 KB
  • Updated last month
  • GitHub
Use this Skill: https://skilld.dev/gh/encoredev/skills/auth

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈36 tokens for metadata: the name and description. ≈1.6k when used: this file.

Description uses 8.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈676 characters, or 8.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Encore Authentication

Instructions

Encore.ts provides a built-in authentication system for identifying API callers and protecting endpoints.

1. Create an Auth Handler

// auth.ts
import { Header, Gateway } from "encore.dev/api";
import { authHandler } from "encore.dev/auth";

// Define what the auth handler receives
interface AuthParams {
  authorization: Header<"Authorization">;
}

// Define what authenticated requests will have access to
interface AuthData {
  userID: string;
  email: string;
  role: "admin" | "user";
}

export const auth = authHandler<AuthParams, AuthData>(
  async (params) => {
    // Validate the token (example with JWT)
    const token = params.authorization.replace("Bearer ", "");
    
    const payload = await verifyToken(token);
    if (!payload) {
      throw APIError.unauthenticated("invalid token");
    }
    
    return {
      userID: payload.sub,
      email: payload.email,
      role: payload.role,
    };
  }
);

// Register the auth handler with a Gateway
export const gateway = new Gateway({
  authHandler: auth,
});

2. Protect Endpoints

import { api } from "encore.dev/api";

// Protected endpoint - requires authentication
export const getProfile = api(
  { method: "GET", path: "/profile", expose: true, auth: true },
  async (): Promise<Profile> => {
    // Only authenticated users reach here
  }
);

// Public endpoint - no authentication required
export const healthCheck = api(
  { method: "GET", path: "/health", expose: true },
  async () => ({ status: "ok" })
);

3. Access Auth Data in Endpoints

import { api } from "encore.dev/api";
import { getAuthData } from "~encore/auth";

export const getProfile = api(
  { method: "GET", path: "/profile", expose: true, auth: true },
  async (): Promise<Profile> => {
    const auth = getAuthData()!;  // Non-null when auth: true
    
    return {
      userID: auth.userID,
      email: auth.email,
      role: auth.role,
    };
  }
);

Auth Handler Behavior

Scenario Handler Returns Result
Valid credentials AuthData object Request authenticated
Invalid credentials Throws APIError.unauthenticated() Treated as no auth
Other error Throws other error Request aborted

Auth with Endpoints

Endpoint Config Request Has Auth Result
auth: true Yes Proceeds with auth data
auth: true No 401 Unauthenticated
auth: false or omitted Yes Proceeds (auth data available)
auth: false or omitted No Proceeds (no auth data)

Service-to-Service Auth Propagation

Auth data automatically propagates to internal service calls:

import { user } from "~encore/clients";
import { getAuthData } from "~encore/auth";

export const getOrderWithUser = api(
  { method: "GET", path: "/orders/:id", expose: true, auth: true },
  async ({ id }): Promise<OrderWithUser> => {
    const auth = getAuthData()!;

    // Auth is automatically propagated to this call
    const orderUser = await user.getProfile();

    return { order: await getOrder(id), user: orderUser };
  }
);

Overriding Auth Data

You can explicitly override auth data when making service-to-service calls:

import { user } from "~encore/clients";

// Override auth data for this specific call
const adminUser = await user.getProfile(
  {},
  { authData: { userID: "admin-123", email: "admin@example.com", role: "admin" } }
);

Common Auth Patterns

JWT Token Validation

import { jwtVerify } from "jose";
import { secret } from "encore.dev/config";

const jwtSecret = secret("JWTSecret");

async function verifyToken(token: string): Promise<JWTPayload | null> {
  try {
    const { payload } = await jwtVerify(
      token,
      new TextEncoder().encode(jwtSecret())
    );
    return payload;
  } catch {
    return null;
  }
}

API Key Authentication

export const auth = authHandler<AuthParams, AuthData>(
  async (params) => {
    const apiKey = params.authorization;
    
    const user = await db.queryRow<User>`
      SELECT id, email, role FROM users WHERE api_key = ${apiKey}
    `;
    
    if (!user) {
      throw APIError.unauthenticated("invalid API key");
    }
    
    return {
      userID: user.id,
      email: user.email,
      role: user.role,
    };
  }
);

Cookie-Based Auth

interface AuthParams {
  cookie: Header<"Cookie">;
}

export const auth = authHandler<AuthParams, AuthData>(
  async (params) => {
    const sessionId = parseCookie(params.cookie, "session");
    
    if (!sessionId) {
      throw APIError.unauthenticated("no session");
    }
    
    const session = await getSession(sessionId);
    if (!session || session.expiresAt < new Date()) {
      throw APIError.unauthenticated("session expired");
    }
    
    return {
      userID: session.userID,
      email: session.email,
      role: session.role,
    };
  }
);

Testing with Auth

Mock authentication in tests using Vitest:

import { describe, it, expect, vi } from "vitest";
import * as auth from "~encore/auth";
import { getProfile } from "./api";

describe("authenticated endpoints", () => {
  it("returns profile for authenticated user", async () => {
    // Mock getAuthData to return test user
    const spy = vi.spyOn(auth, "getAuthData");
    spy.mockImplementation(() => ({
      userID: "test-user-123",
      email: "test@example.com",
      role: "user",
    }));

    const profile = await getProfile();
    expect(profile.email).toBe("test@example.com");

    spy.mockRestore();
  });
});

The mock does not reach calls made through ~encore/clients. To call an auth: true endpoint on another service from a test, pass { authData: ... } as the second argument (see "Overriding Auth Data" above).

Guidelines

  • Auth handlers must be registered with a Gateway
  • Use getAuthData() from ~encore/auth to access auth data
  • getAuthData() returns null in unauthenticated requests
  • Auth data propagates automatically in service-to-service calls
  • Throw APIError.unauthenticated() for invalid credentials
  • Keep auth handlers fast - they run on every authenticated request

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at e86a3ab. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 weeks ago.

Activeupdated last month
Other metadata
when_to_use
User wants to require login on an endpoint, restrict an endpoint to authenticated/signed-in users, validate a bearer token / JWT / API key from an Authorization header, read the current user inside a handler (`getAuthData`), set up an `authHandler<AuthParams, AuthData>` or `Gateway`, return 401/403 from a handler, or set `auth: true` on `api(...)`. Trigger phrases: "protect this endpoint", "only authenticated users", "require login", "Authorization header", "bearer token", "401", "403", "who is calling", "current user".
  • TypeScript
  • authentication
  • authorization
  • jwt
  • api-key
  • bearer-token
  • encore
  • endpoint-protection

README badge

README badge for encoredev/skills/auth

Implement authentication in Encore.ts endpoints using an authHandler and getAuthData, supporting JWT tokens, API keys, and cookies. Protect endpoints with auth: true to require login and access user identity in handlers.

Generated from the current SKILL.md.

Does this skill work with JWT tokens and API keys?
Yes. The skill covers JWT token validation via the `jose` library and API key authentication via database lookup. Both patterns are shown with example code.
How do I restrict an endpoint to authenticated users only?
Set `auth: true` on the endpoint config. Requests without valid credentials will receive a 401 response.
Can I access the current user inside a handler?
Yes, use `getAuthData()` from `~encore/auth` to retrieve the authenticated user's data (userID, email, role, etc.).
Does auth propagate to internal service-to-service calls?
Yes, auth data automatically propagates to calls between Encore services. You can override it per-call by passing `authData` in the options.
What happens if the auth handler throws an error?
If it throws `APIError.unauthenticated()`, the request is treated as unauthenticated. Any other error aborts the request.

Generated from the current SKILL.md. These answers refresh after source changes.