키 관리 — /v1/keys
관리 키로 학생 키를 한 번에 만들고 · 한도와 기한을 바꾸고 · 끕니다.
학기 초에 학생 서른 명의 키를 만들고, 학기 끝에 한 번에 끄는 일을 스크립트로 하실 때 쓰는 문이에요. 대시보드 API 키 화면에서 하는 일과 같은 규칙으로 돌아요 — 키 자리가 모자라면 하나도 안 만들고, 초·중·고 학교 지갑의 새 키는 학생 키가 기본이에요.
학생 키 30개 — 하루 한도 · 학기 끝 날까지
curl https://oneport.kr/v1/keys \
-H "Authorization: Bearer $ONEPORT_MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{ "count": 30, "name_prefix": "3학년 2반", "daily_limit_credits": 300, "expires_on": "2027-02-28" }'응답 data 의 줄마다 key 칸에 원문이 들어 있어요. 원문은 이 응답에서 한 번만 나가요 — 바로 나눠 드리거나 안전한 곳에 보관하세요. 중간에 멈추면 그때까지 만든 키(원문 포함)를 201 로 드리고 incomplete: true 와 error 를 같이 실어요 — 모자란 만큼 다시 부르시면 돼요.
문 다섯#
경로
| 파라미터 | 받는 값 | 저희가 하는 일 |
|---|---|---|
| GET /v1/keys | limit · offset | 켜진 API 키 목록이에요(사람의 채팅 키는 빼요 · 최근 것 먼저). limit 은 1–500, 기본 100이고 total · has_more 를 같이 드려요. |
| POST /v1/keys | JSON | 키를 하나 또는 여러 개 만들어요. count 는 100까지이고, 키 자리가 모자라면 하나도 안 만들어요. |
| GET /v1/keys/{id} | 키 id | 키 하나를 봐요. 다른 지갑의 id · 꺼진 키 · 사람의 채팅 키는 404 예요. |
| PATCH /v1/keys/{id} | JSON | 보낸 칸만 고쳐요. null 을 보내면 그 한도나 기한을 지워요. 바뀐 줄을 그대로 돌려드려요. |
| DELETE /v1/keys/{id} | 키 id | 키를 꺼요. 바로 막히고 되돌릴 수 없어요 — 다시 필요하면 새로 만드세요. |
만들기 · 고치기 칸#
요청 본문 (JSON)
| 파라미터 | 받는 값 | 저희가 하는 일 |
|---|---|---|
| count | 정수 1–100 | 만들 개수예요. 안 보내시면 하나예요. 여러 개면 이름 끝에 1, 2, 3 … 을 붙여요(만들기만). 동시에 보낸 다른 요청과 겹쳐 자리를 넘으면 이번에 만든 키를 모두 끄고 409 로 알려드려요. |
| name · name_prefix | 문자열 (40자 · 20자) | 키 이름이에요. 하나면 name(없으면 name_prefix) 그대로, 여러 개면 name_prefix 뒤에 번호를 붙여요. 고칠 때 name 에 null 을 보내면 이름을 지워요. 「채팅 · 」으로 시작하는 이름은 팀 채팅 키 이름이라 못 써요. |
| audience | student · teacher | 학생 키면 웹 검색 · 웹 페이지 읽기 · 원격 MCP · 영상 만들기가 막혀요. 초·중·고 학교 지갑은 안 보내시면 학생이에요. 쓰임새를 나누지 않는 지갑에 student 를 보내면 400 이에요. |
| monthly_limit_credits | 정수 크레딧 또는 null | 이 키의 이번 달 한도예요. null 이면 지갑 크레딧까지 써요. 다음 달 1일 한국 시간 0시에 다시 열려요. |
| daily_limit_credits | 정수 크레딧 또는 null | 이 키의 오늘 한도예요. 월 한도보다 클 수 없고, 한국 시간 0시에 다시 열려요. |
| expires_on | 날짜 YYYY-MM-DD 또는 null | 이 날까지 써요. 그다음 날 한국 시간 0시에 저절로 닫혀요. 오늘보다 이른 날은 받지 않아요 — 지금 끄려면 DELETE 예요. |
응답 한 줄
{
"object": "api_key",
"id": "8f0c…",
"name": "3학년 2반 1",
"key_prefix": "sk-so-a1b2c3…",
"audience": "student",
"monthly_limit_credits": null,
"month_used_credits": 0,
"daily_limit_credits": 300,
"day_used_credits": 0,
"expires_at": "2027-02-28T15:00:00.000Z",
"usable_until": "2027-02-28",
"created_at": "2026-10-15T01:00:00.000Z",
"last_used_at": null,
"key": "sk-so-…"
}key 칸(원문)은 만들 때 응답에만 있어요. 목록 · 하나 보기 · 고치기 응답엔 없어요. 위 표에 없는 칸 이름(예: monthly_limit · expires_at)을 보내시면 그냥 넘기지 않고 400 으로 이름을 알려드려요. 오류는 401(관리 키가 아니거나 닫힘) · 400(칸이 틀림 · 자리가 모자람) · 404(그 키가 없음) · 409(다른 요청과 겹쳐 자리를 넘음) · 503(저희 쪽 일시 장애)이에요.
이 문서를 AI 에게 넘기시려면 마크다운 원문을 쓰세요 — 주소 끝에 .md 를 붙이면 나와요.