[Next.js] API 라우트 보호하기 - Unkey

 

OpenAI 같은 LLM(대형 언어 모델) 기반 API로 기능을 개발하다 보면, 자연스럽게 사용량 제한이 필요해진다. Unkey라는 API 관리 플랫폼을 이용하면 API 키 관리, 요청 빈도 제한, 사용량 분석 같은 기능을 손쉽게 구현할 수 있다. API 엔드포인트별로 요청량을 제한하거나 사용자마다 다른 제한 정책을 설정할 수도 있다. Unkey 무료 요금제(Free Tier)는 API 키 1000개, 월 15만 건의 요청까지 사용할 수 있기 때문에 개인 프로젝트에 사용하기 딱 좋다.

 

Next.js를 사용한다면 Unkey에서 제공하는 SDK를 이용해서 더 편하게 통합할 수 있다. 예를 들어 서버 액션이나 API 라우트에 미들웨어처럼 적용하여 인증된 요청만 처리하거나 사용량 제한을 적용할 수 있다.

 

Unkey는 크게 발급된 Key로 사용자/서비스를 구분하는 API Key 방식과, IP 주소/ID 같은 임의 식별자를 사용하는 Ratelimit 방식으로 나뉜다. 인증 없는 엔드포인트를 보호할 땐 Ratelimit, 키별 접근 권한과 할당량을 관리할 땐 API Key 방식이 적합하다.

 

 

Ratelimiting (사용량 제한)

---

기본 설정

❶ Unkey 계정 생성  

 

❷ Unkey root key 생성. 키 생성 페이지에서 create_namespace, limit 권한에 체크한다.

 

❸ @unkey/ratelimit 패키지 설치

pnpm install @unkey/ratelimit

 

❹ Root Key 환경 변수 설정

# .env.local
UNKEY_ROOT_KEY="..."

 

❺ 라우트 보호 로직 작성. Ratelimit 생성자로 limiter 인스턴스를 생성한 후 limit 메서드로 식별자에 대한 요청 제한 상태를 확인할 수 있다. limit 메서드는 성공 여부(success), 남은 요청 횟수(limit) 등의 정보를 담은 RatelimitResponse 객체를 반환한다. 아래 예시에서는 IP 주소를 식별자로 사용했지만 ID, 이메일 등 다른 고유한 식별자를 자유롭게 사용할 수 있다.

// app/api/subtask/route.ts
import { Ratelimit } from '@unkey/ratelimit';

const limiter = new Ratelimit({
  // 사용할 네임스페이스 이름
  namespace: 'kanban.subtask',
  // duration 기간 동안 허용할 최대 요청 수
  limit: 30,
  // Unkey API 인증을 위한 루트키 설정
  duration: '12h',
  // 루트키 설정
  rootKey: process.env.UNKEY_ROOT_KEY ?? '',
  // Unkey 서비스의 성능 측정 데이터 수집 비활성화 (기본값 false)
  disableTelemetry: true,
  // 요청 제한을 비동기적으로 처리. 속도 빠르지만 정확도 다소 떨어짐(98%)
  async: true,
});

export async function POST(req: NextRequest) {
  // 요청 헤더에서 클라이언트 IP 주소 조회 (IP 주소를 식별자로 사용)
  const ip = req.headers.get('x-forwarded-for') ?? 'unknown';
  // limit 메서드로 넘긴 식별자의 요청 제한 상태 확인
  const rateLimit = await limiter.limit(ip);
  // 요청 횟수를 모두 사용했을 때
  if (!rateLimit.success) {
    return new Response('Rate limit exceeded', { status: 429 });
  }

  // 요청 처리 계속...
}

 

❻ Unkey 대시보드의 Ratelimit 메뉴를 보면 지정한 네임스페이스가 자동으로 생성되어 있는 걸 확인할 수 있다. 네임스페이스를 클릭해 보면 요청 성공/실패 여부와 같은 세부 정보를 확인할 수 있다.

 

동기 vs 비동기 방식

💡 엣지(Edge)는 인터넷 인프라에서 사용자와 가까운 서버를 가리킨다.

 

Ratelimit 생성자의 async 옵션은 기본적으로 false로 지정되어 있어서 동기적으로 작동한다. 이는 limit 메서드를 호출(요청 제한 상태 확인)해서 응답을 받을 때까지 대기(블로킹)해야 함을 의미한다. Unkey는 지연(latency)을 줄이기 위해 요청 위치에 따라 가장 가까운 엣지로 origin을 재배치하지만 제한 상태를 확인하려면 여전히 origin과의 요청/응답 왕복이 필요하다.

 

만약 동일한 식별자가 여러 지역에서 동시에 요청을 보낸다면 물리적으로 가장 가까운 지역의 식별자가 우선적으로 선택된다. 나머지 지역에 있는 식별자는 상대적으로 더 먼 곳에서 서버와 통신해야 하므로 지연이 더 발생할 수 있다. 이처럼 동기 방식은 다소 느릴 수 있지만 모든 요청이 항상 동일한 origin을 기준으로 검증하기 때문에 정확성이 높은 장점이 있다.

 

비동기 방식은(async 옵션 true) 로컬 엣지 캐시의 limit 상태를 먼저 사용한 후 백그라운드에서 비동기적으로 origin과 동기화한다. 지연 시간은 훨씬 줄어들지만 정확도가 다소 떨어지는 단점이 있다(약 98%). 만약 동일한 식별자가 다른 지역에서 동시에 요청을 보내온다면 엣지에 동기화되기 전까지 요청 제한을 초과할 수 있는 가능성도 존재한다.

 

비동기 방식에서 RatelimitResponse 객체의 remaining 값은 정확하지 않을 수도 있으므로, success 속성 값을 통해 요청 허용 여부를 판단하는 게 좋다. (참고 링크)

 

Unkey 팀은 엄격한 정확도를 요구하는 상황을 제외하곤 비동기 모드 사용을 권장하고 있다.

 

Override

Override 기능을 이용하면 코드 변경 없이 특정 조건(이메일, 도메인 등)에 따라 Rate Limit을 유연하게 설정할 수 있다. 식별자에는 와일드카드(*)를 활용한 패턴 매칭을 지원한다. 예) *@sales.com, *.abc.com

대시보드 - Ratelimit 메뉴 - 우측 상단 Override Identifer 버튼을 클릭하면 오버라이드를 설정할 수 있다.

 

식별자에 이미 Rate Limit을 적용했더라도 Override 설정이 이를 덮어쓴다. 여러 Override 규칙이 있을 땐 정확히 일치하는 규칙이 와일드카드 규칙보다 높은 우선순위를 가진다. 예를 들어 *@abc.com, sales@abc.com이 함께 설정된 경우, 더 구체적인 규칙인 sales@abc.com이 우선적으로 적용된다.

 

Override 변경사항은 60초 이내에 전 세계 엣지 로케이션에 적용된다. 코드 수정 → 검토 → 배포 과정 없이 대시보드를 통해 규칙을 수정할 수 있어서 운영 효율성이 크게 향상된다.

 

 

API Keys (라우트 보호)

---

기본 설정

❶ Unkey 계정 생성  

 

❷ Unkey 대시보드에서 API 생성

 

❸ UNKEY_API_ID 환경 변수 추가

# .env.local
UNKEY_API_ID="..."

 

❹ @unkey/nextjs 패키지 설치

pnpm add @unkey/nextjs

 

❺ 라우트 보호 로직 추가. 기존 Next.js 라우트를 withUnkey 함수로 감싸면 요청을 받을 때마다 내부적으로 API 키를 검증한다. 키 검증을 성공하면 라우트 본문이 실행되고, 실패하면 handleInvalidKey 메서드가 실행된다.

// app/api/subtask/route.ts
import { withUnkey } from '@unkey/nextjs';

export const POST = withUnkey(
  async (req) => {
    /* API 키 검증 성공시 라우트 본문 실행 */
  },
  {
    // Unkey 서비스의 성능 측정 데이터 수집 비활성화 (기본값 false)
    disableTelemetry: true,
    // 검증 대상 API 키가 속한 API ID
    apiId: process.env.UNKEY_API_ID,
    // API 키 검증 실패 시 에러 응답 커스텀
    handleInvalidKey(_req, res) {
      console.error('API key validation failed:', res?.code);
      return new Response('Unauthorized', { status: 401 });
    },
  },
);

 

❻ 새로운 API Key를 생성하고 Next.js 라우트로 요청 테스트를 보내본다.

curl -XPOST 'http://localhost:3000/api/<PATH>' \
  -H "Authorization: Bearer <YOUR_KEY>"

 

Next.js 미들웨어 설정

💡 Next.js 미들웨어는 기본적으로 Edge 런타임에서 실행된다. Edge 런타임에선 요청마다 독립적인 실행 환경을 가진다(요청마다 별도 인스턴스).

 

만약 회원가입/로그인이 없는 간단한 프로젝트라면 만료일이 지정된 API Key를 쿠키에 저장해 두고, 요청받을 때마다 Next.js 미들웨어에서 쿠키를 조회하여 Authorization 헤더에 추가할 수도 있다. 참고로 withUnkey 함수는 기본적으로 Authorization 헤더에서 API Key를 찾는다. 원한다면 getKey 함수를 이용해서 API Key 조회 로직을 커스텀할 수도 있다.

 

1. 클라이언트 요청
2. Next.js 미들웨어 - 쿠키에서 API Key 확인.
   • 쿠키에 API Key 없으면 생성 후 응답 쿠키 설정
   • 요청 헤더에 Authorization 필드 추가
3. Next.js 라우트에서 API Key 검증 후 응답

 

 

미들웨어 함수로 전달되는 Request 객체는 읽기 전용이므로 요청 헤더를 수정하려면 헤더 복제/수정 → 응답 객체의 헤더를 덮어쓰는 작업이 필요하다. NextResponse.next()를 이용하여 요청 헤더를 수정하면, 수정된 헤더가 API 라우트 핸들러의 Request 객체에 반영된다. response.cookie.set()을 통해 응답 쿠키를 설정하면 Set-Cookie 헤더가 추가되어 클라이언트가 이후 요청에서 해당 쿠키를 자동으로 포함시킨다.

// src/middleware.ts
import { type NextRequest, NextResponse } from 'next/server';
import { retrieveSubtaskUnkey, setUnkeySessionCookie } from '@/lib';

export async function middleware(req: NextRequest) {
  // ...

  // 쿠키에서 API Key를 확인하고 없으면 새로 생성하는 유틸리티 함수
  const { unkeyValue, isNewKey } = await retrieveSubtaskUnkey(req);
  // 요청 헤더 복제
  const headers = new Headers(req.headers);
  // 복제한 요청 헤더에 Authorization 필드 추가
  headers.set('Authorization', `Bearer ${unkeyValue}`);
  // 복제한 헤더를 포함한 요청 객체를 생성하여 다음 처리 단계로 전달
  const response = NextResponse.next({ request: { headers } });
  // API Key를 새로 생성했다면 응답 쿠키에 저장(다음 번 요청 때 확인하기 위해)
  if (isNewKey && unkeyValue) setUnkeySessionCookie(response, unkeyValue);

  // ...
  return response;
}

// '/api' 경로 이하의 모든 요청에 미들웨어 적용
export const config = { matcher: ['/api/:path*'] };

 

Next.js는 프로젝트당 1개의 middleware.ts 파일만 허용한다. 때문에 주요 로직은 아래처럼 별도의 모듈로 구성한 뒤 미들웨어에서 불러오는 방식을 권장한다. 쿠키를 설정할 땐 httpOnly, secure, sameSite 옵션을 지정하는 것이 보안상 유리하다. API 키 생성은 @unkey/api 패키지를 설치한 후, unkey.keys.create() 함수를 호출하면 된다. 이때 만료 시간(expires), 요청 제한(ratelimit), remaining 초기화(refill), 메타데이터(meta) 등을 유연하게 지정할 수 있다.

// lib/unkey.ts
export const UNKEY_COOKIE_NAME = 'unkey_session';
export const UNKEY_EXPIRY_HOURS = 72;
export const UNKEY_SUBTASK_LIMIT = 30;
export const UNKEY_NAMESPACE = { SUBTASK: 'kanban.subtask' } as const;

// 쿠키에 API Key를 설정하는 함수
export const setUnkeySessionCookie = (
  response: NextResponse,
  unkeyValue: string,
) => {
  response.cookies.set({
    name: UNKEY_COOKIE_NAME,
    value: unkeyValue,
    httpOnly: true, // 자바스크립트로 쿠키 접근 제한(document.cookie)
    secure: !isDev(), // HTTPS 연결에서만 쿠키 전송
    maxAge: 60 * 60 * UNKEY_EXPIRY_HOURS, // 쿠키 만료 시간 (초 단위)
    sameSite: 'strict', // 동일 사이트 요청에서만 쿠키 전송
    path: '/api', // /api 경로에서만 쿠키 전송
  });
};

// 쿠키에서 API Key를 확인하고 없으면 새로 생성하는 함수
export const retrieveSubtaskUnkey = async (req: NextRequest) => {
  let isNewKey = false;
  let unkeyValue = req.cookies.get(UNKEY_COOKIE_NAME)?.value ?? null;

  if (!unkeyValue) {
    isNewKey = true;
    const clientInfo = getClientInfo(req);
    unkeyValue = await createUnkey(clientInfo);
  }

  return { unkeyValue, isNewKey };
};

// Unkey API 키를 생성하는 함수.
export async function createUnkey(meta: ClientInfo) {
  const unkey = new Unkey({
    rootKey: getEnv('UNKEY_ROOT_KEY'),
    disableTelemetry: true,
  });

  try {
    const ownerId = nanoid(10);
    const { result, error } = await unkey.keys.create({
      apiId: getEnv('UNKEY_API_ID'),
      prefix: UNKEY_NAMESPACE.SUBTASK, // 키에 추가될 접두사
      ownerId: ownerId, // 유저 식별을 위한 ID
      name: meta.realIp ?? meta.ip ?? 'unknown',
      meta: { createdAt: new Date().toISOString(), ...meta },
      expires: addHours(new Date(), UNKEY_EXPIRY_HOURS).getTime(),
      ratelimit: { duration: 1000, limit: 2, async: true }, // 1초간 2번 요청 허용
      remaining: UNKEY_SUBTASK_LIMIT,
      refill: { interval: 'daily', amount: UNKEY_SUBTASK_LIMIT }, // 자정마다 amount 만큼 remaining 리셋
      enabled: true,
    });

    if (error) {
      console.error(error.message);
      return null;
    }

    console.log(`Created new Unkey key for user ${ownerId}`);
    return result.key;
  } catch (error) {
    console.error('Failed to create Unkey key', error);
    return null;
  }
}

 

참고로 Next.js에서 쿠키를 읽고(read) 쓸 수 있는(write) cookies()라는 유틸리티 함수도 제공한다. 쿠키 특성상 서버 컴포넌트에선 읽기만 가능하고, 서버 액션이나 라우트 핸들러에선 읽기/쓰기를 모두 지원한다.

 

메타데이터

💡 프록시(중간에서 요청을 전달하는 서버)를 서비스 앞에 배치하면 실제 사용자 IP 식별이 어려워진다. 그래서 X-Forwarded-For 헤더를 통해 원본 사용자 IP를 전달한다. 그러나 Vercel은 IP 스푸핑 공격을 방지하기 위해 외부에서 전송된 X-Forwarded-For 헤더 값을 무시하고, 클라이언트의 실제 IP 주소로 덮어쓴다. IP 스푸핑(Spoofing)이란 공격자가 네트워크 상에서 자신의 실제 IP 주소를 은폐하고 다른 IP 주소로 위장하여 통신하는 기법이다.

 

프로젝트를 Vercel에 배포했다면 동적 요청(Dynamic Request)은 Vercel Function(서버리스 함수)을 통해 처리되며, 이때 Request 객체를 통해 다양한 헤더 정보를 얻을 수 있다. Unkey API Key를 생성할 때 이러한 헤더 정보를 메타데이터에 저장해 두면 이후 로그를 분석하거나 통계를 수집할 때 유용하게 활용할 수 있다.

// lib/utils.ts
import { type NextRequest, userAgent } from 'next/server';

export const getClientInfo = (req: NextRequest) => {
  // Next.js에서 제공하는 userAgent 함수를 사용하여 OS, 기기 등 정보 추출
  const { browser, os, device, isBot } = userAgent(req);
  // 추출한 정보를 agent 객체에 저장
  const agent = { browser, os, device, isBot };
  // 클라이언트의 원래 IP 주소와 요청이 거쳐온 프록시 서버들의 IP 주소를 추적하는 표준 헤더(콤마로 구분)
  const ip = req.headers.get('x-forwarded-for');
  // 클라이언트의 실제 IP 주소
  const realIp = req.headers.get('x-real-ip');
  // 클라이언트의 국가 정보 예) KR
  const country = req.headers.get('x-vercel-ip-country');
  // 클라이언트의 도시 정보 예) Seocho-gu
  const city = req.headers.get('x-vercel-ip-city');
  // 리퍼러 정보
  const referrer =
    req.headers.get('referer')?.replace(/https?:\/\/([^/]+).*/i, '$1') ??
    'direct';

  return { agent, ip, realIp, country, city, referrer };
};

 

Next.js의 userAgent 유틸리티 함수는 HTTP 요청 헤더의 User-Agent 문자열을 분석해서 isBot, os, browser 같은 다양한 클라이언트 정보를 반환한다.

 

 

전체 요청 제한

라우트에 단일 API Key를 설정하여 전체 요청 횟수(remaining)를 통합 관리하고, Ratelimit을 통해 각각의 사용량을 제한하면 API Key 수준에서 총사용량을 제어하면서 개별 식별자의 과도한 요청도 방지할 수 있다. 예를 들어 개별 식별자의 요청 횟수가 아직 남아 있더라도 API Key의 전체 요청 횟수를 모두 소진했다면 요청이 차단된다.

 

withUnkey를 통해 API Key의 남은 요청 횟수를 검사한 후, 개별 식별자의 Ratelimit을 검사하는 예시.

// app/api/subtask/route.ts
// API Key의 남은 요청 횟수 검사
export const POST = withUnkey(
  async (req) => {
    const ip = req.headers.get('x-forwarded-for') ?? 'unknown';
    const rateLimit = await limiter.limit(ip);
    // 개별 식별자의 남은 요청 횟수 검사
    if (!rateLimit.success) {
      return new Response('Rate limit exceeded', { status: 429 });
    }

    // 요청 처리 계속...
  },
  {
    // withUnkey 옵션...
  },
);