서비스마다 별도의 계약, 별도의 credential, 별도의 세션 관리가 필요한 것이 보통입니다. managed key는 이 부담을 하나로 줄입니다. 서비스별 credential은 전부 APIFuse이 자기 쪽에 보관하고, 통합 코드는 bearer 토큰 하나로 인증합니다. 서비스가 credential을 교체하거나 세션을 재협상해도 호출하는 쪽에서는 아무것도 바뀌지 않습니다.

하나의 key, 모든 서비스

managed key는 APIFuse 대시보드에서 발급하는 불투명한 bearer 토큰입니다. key의 scope가 허용하는 모든 서비스를 호출할 수 있으며, 새 key는 기본적으로 전체 scope를 가집니다. key 안에는 어떤 서비스 credential도 담겨 있지 않으므로, 서비스 쪽 설정을 건드리지 않고 언제든 폐기하거나 교체할 수 있습니다.

live key와 sandbox key

key의 접두사가 환경을 구분합니다. 두 환경은 완전히 격리되어 있습니다. sandbox key로 만든 객체는 실제 매장이나 서비스에 전달되지 않고 live key에서 보이지도 않으며, 반대 방향도 마찬가지입니다. 접두사만 다를 뿐 두 key의 형식과 사용법은 동일하므로, 환경 변수 값만 바꾸면 같은 코드가 그대로 동작합니다.

Authorization 헤더

모든 요청은 표준 bearer 헤더로 key를 전달합니다. query parameter 방식이나 서비스별 헤더는 없습니다. key가 없거나 유효하지 않으면 에러 envelope에 code unauthorized가 담긴 401이 반환됩니다.

curl "https://api.frism.dev/v1/catch-table/restaurants?area=seongsu&cuisine=japanese" \
  -H "Authorization: Bearer frism_test_k3xample"

{
  "items": [
    {
      "id": "res_01J8Q9W3TE",
      "name": "Sushi Aoyagi",
      "area": "seongsu",
      "cuisine": "japanese",
      "price_band": "high",
      "bookable_online": true
    }
  ],
  "next_cursor": "cur_9f2kq"
}

위 호출은 의 입니다.

key 보관

managed key는 서버 측 secret입니다. 환경 변수나 secret manager에 보관하고, 백엔드에서 보내는 요청에만 첨부합니다.

• 클라이언트 번들, 모바일 앱, 공개 저장소에 key를 넣지 않습니다. 브라우저가 내려받는 것은 전부 공개된 것입니다.
• 브라우저와 앱의 트래픽은 자체 백엔드를 거치게 하고, key는 그 백엔드가 첨부합니다.
• 환경마다 별도의 환경 변수(예: FRISM_API_KEY)를 사용해 live와 sandbox 값이 섞이지 않게 합니다.

// 서버에서만 실행합니다. key는 환경 변수에서 읽습니다.
const key = process.env.FRISM_API_KEY;
if (!key) throw new Error("FRISM_API_KEY is not set");

const response = await fetch(
  "https://api.frism.dev/v1/catch-table/restaurants?area=seongsu&cuisine=japanese",
  { headers: { Authorization: `Bearer ${key}` } },
);
if (!response.ok) {
  throw new Error(`APIFuse error: ${response.status}`);
}

const page = await response.json();
console.log(page.items[0].name); // "Sushi Aoyagi"

key 교체

여러 key가 동시에 유효할 수 있으므로 교체에 다운타임이 없습니다. 주기적으로 교체하고, 유출이 의심되면 즉시 교체합니다.

1. 대시보드에서 같은 scope를 가진 두 번째 key를 생성합니다.
2. 새 key를 환경 변수에 배포하고, 트래픽이 새 key로 인증되는지 확인합니다.
3. 이전 key를 폐기합니다. 이전 key를 계속 쓰는 요청은 그 시점부터 401 unauthorized를 받습니다.

linked-account 서비스

대부분의 서비스는 managed key만으로 동작합니다. 와 는 최종 사용자를 대신해 동작하는 linked-account 서비스입니다. 사용자가 자신의 계정을 통합에 한 번 연결하면, 그 이후의 API 호출 방식은 달라지지 않습니다. 요청은 여전히 같은 managed key로 인증하고, 사용자의 서비스 credential을 여러분이 보거나 저장할 일은 없습니다. scope 규칙도 동일하게 적용됩니다.

다음으로 key가 호출할 수 있는 범위를 좁히는 방법은 에서, 401과 403의 정확한 모양은 에서 확인합니다.