지식 베이스

API 키

작업마다 키 하나, 필요한 범위와 발신자로만 제한하고 모든 호출을 기록합니다.

세부 사항

본인 소유 워크스페이스의 설정 → API 키에서 만듭니다. 시크릿은 한 번만 표시되며 모든 키는 oe_live_ 키입니다.
키는 선택한 범위만 가지며 새 키는 emails:send로 시작합니다. 역할을 붙일 수도 있는데, 이는 두 번째 권한 부여가 아니라 상한선입니다. GET /ping은 키가 지정한 범위와 역할이 남겨 준 범위를 돌려주므로, 키가 분명히 가진 범위에서 403이 나도 원인이 보입니다.
발송 범위에는 도메인 전체 최대 25개와 개별 주소 최대 50개를 넣을 수 있습니다. 도메인 전체는 나중에 추가된 주소도 포함하며, 목록 밖의 발신자는 403으로 거부됩니다.
선택적 만료를 설정하면 키가 최대 10년 뒤에 스스로 만료됩니다.
교체는 시크릿만 바꿉니다. ID, 범위, 발송 범위, 요청 기록은 이어지고, 새 시크릿이 만들어지는 순간 이전 시크릿은 작동을 멈춥니다. keys:write를 가진 키는 API로 스스로를 교체할 수 있습니다. 폐기는 삭제가 아니라 업데이트이므로 이후 호출에는 revoked_api_key가 전달됩니다.
인증된 모든 호출은 메서드, 경로, 상태, 오류 코드, 소요 시간, IP, 사용자 에이전트와 함께 기록되며 본문이나 쿼리 문자열은 기록하지 않습니다. 키 페이지에서는 이를 분석, 활동, 요청으로 보여 주며, 가장 많이 쓰이는 경로와 실패 빈도, 지연 시간 중앙값을 함께 표시하고, 같은 화면에서 여러 키를 한꺼번에 볼 수 있습니다. 로그는 잘라내지 않고 보관합니다.
이 페이지에서 하는 모든 일은 API와 SDK에서도 할 수 있습니다. GET /keys와 GET /keys/{id}는 시크릿을 뺀 키를 읽고, POST /keys는 키를 만들고, PATCH /keys/{id}는 이름을 바꾸고 스코프나 발신 범위를 바꾸며 키를 끄고 다시 켜고, rotate, revoke, delete는 이름 그대로의 일을 합니다. 요청 로그와 활동도 키 하나든 전부든 이 페이지의 필터로 같은 방식으로 읽습니다. 읽기에는 keys:read, 모든 변경에는 keys:manage가 필요하며, 누군가 주지 않는 한 어떤 키도 이 두 스코프를 갖지 않습니다. MCP 서버도 listApiKeyRequests와 listApiKeyActivity로 로그와 활동을 읽습니다.
키는 자신보다 넓은 키를 만들거나 그런 키에 닿지 않습니다. 스코프, 역할, 만료, 모드, 발신 범위가 모두 호출하는 키 안에 있어야 합니다. 재인증은 키로 한 호출에는 적용할 수 없으므로 keys:manage는 자격 증명을 만들어 내는 자격 증명입니다. 키를 발급하는 자동화에만, 자체 역할·발신 범위·만료와 함께 주고, 그 모든 행동이 기록되는 활동 탭을 지켜보세요.
없는 것: 키를 IP 주소에 묶을 수 없고, 테스트 모드 키는 만들 수 없습니다.