API 키

GET /keys는 호출자가 볼 수 있는 모든 키를 최신순으로 한 페이지씩 나열하며, 상태, 스코프, 역할, 발신 범위, 마지막 사용 시점, 만든 사람과 마지막으로 바꾼 사람을 함께 보여 줍니다. GET /keys/{id}는 하나를 읽습니다. 어떤 읽기도 시크릿을 돌려주지 않으며, 두 키를 구별하는 데는 maskedKey로 충분합니다. 둘 다 keys:read가 필요합니다.

{  "object": "api_key",  "id": "4c1b257a66287fd113bd89d0",  "name": "Billing sender",  "maskedKey": "oe_live_4c1b…kX7a",  "status": "active",  "scopes": ["emails:send"],  "roleId": null,  "domainAllowlist": ["billing.acme.com"],  "expiresAt": "2026-12-22T09:00:00.000Z",  "lastUsedAt": "2026-09-23T08:14:02.000Z",  "createdBy": { "kind": "apiKey", "name": "API key Provisioner", "label": "API key Provisioner" }}

• —POST /keys는 키를 만들고 그 시크릿을 token으로 한 번만 돌려줍니다. 생략하면 스코프는 emails:send이고 역할, 발신 범위, 만료는 호출자의 것을 따릅니다.
• —PATCH /keys/{id}는 키 이름을 바꾸고, 스코프나 발신 범위를 교체하며, enabled로 키를 끄고 켭니다. 끄기는 되돌릴 수 있는 선택입니다. 키는 모든 것을 유지하고 다시 켜질 때까지 inactive_api_key로 거부됩니다.
• —POST /keys/{id}/rotate는 키에 새 시크릿을 주고 한 번만 돌려줍니다. 이전 시크릿은 호출이 돌아오는 순간 작동을 멈춥니다.
• —POST /keys/{id}/revoke는 키를 영구히 폐기하며 reason은 선택입니다. 그 뒤 DELETE /keys/{id}가 키를 목록에서 없애고 기록은 남깁니다.
• —모두 keys:manage가 필요합니다. 호출하는 키 자신을 교체하는 것은 POST /keys/self/rotate와 똑같이 keys:write로도 됩니다.

모든 변경은 그것을 하는 키와 대조됩니다. 어느 축에서든 호출자 밖으로 나가게 될 키는 403 beyond_caller_authority로 거부되며, param이 그 축을 알려 줍니다:

• —스코프: 호출자가 자기 역할로 좁혀진 뒤에 가진 스코프만.
• —역할: 역할로 상한이 정해진 호출자는 같은 역할로 상한이 정해진 키만 만들고 관리할 수 있습니다.
• —만료: 만료가 있는 호출자는 그보다 늦게 만료되지 않는 키만 만들고 관리할 수 있습니다.
• —모드: 테스트 키는 테스트 키에만 닿습니다.
• —발신 범위: 호출자 자신의 범위 안에 있는 도메인과 주소만. 주소 하나를 가졌다고 그 도메인 전체를 가진 것은 아닙니다.

콘솔은 키를 만들거나 교체하기 전에 다시 인증하도록 요구합니다. 키로 한 호출에는 그렇게 요구할 수 없으므로 keys:manage는 자격 증명을 만들어 내는 자격 증명입니다. 이것을 가진 키가 유출되면 자기 범위 안에서 자신만의 키를 만들 수 있고, 그 키들은 유출된 키가 폐기된 뒤에도 계속 작동합니다.

• —keys:manage는 키 발급이 일인 자동화에만 주고, 메일을 보내는 키에는 절대 주지 마세요.
• —그 키를 좁히세요: 역할, 발신 범위, 만료. 그 키가 만드는 모든 것은 세 가지를 물려받으며 결코 넘을 수 없습니다.
• —GET /keys/activity를 지켜보세요. 그 키가 만들고, 바꾸고, 폐기한 모든 키가 이름과 함께 기록되므로, 유출은 예상하지 못한 키로 드러납니다.
• —keys:read는 IP 주소와 사용자 에이전트를 포함한 요청 로그를 드러냅니다. 감사용 접근으로 다루세요.

GET /keys/requests와 GET /keys/{id}/requests는 키가 한 모든 인증된 호출을 최신순으로 읽습니다: 메서드, 경로, 상태, 오류 코드, 소요 시간, IP, 사용자 에이전트. 본문이나 쿼리 문자열은 담지 않습니다. keyIds, failedOnly, since, until은 콘솔이 제공하는 필터입니다. GET /keys/activity와 GET /keys/{id}/activity는 키에 일어난 일을 읽고, actor가 누가 했는지를 @username이나 API key <name>으로 알려 줍니다. 아무것도 지워지지 않으며, 삭제된 키도 기록을 유지합니다.