Part 3

Key Management API

APIs for issuing, retrieving, and revoking student keys. Called from your institution's backend; all requests require org_key.

Common

항목	값
Base URL	https://naia-gateway-181404717065.asia-northeast3.run.app
인증 헤더	Authorization: Bearer {ORG_KEY}
Content-Type	application/json

Issue Student Key

학생 로그인 시 호출합니다. 같은 user_id로 재호출하면 기존 키를 반환합니다.

http

POST /v1/keys

요청

json

{
  "user_id": "student@example.com",
  "name": "홍길동",
  "metadata": {
    "type": "user_key",
    "org_key_id": "<저희가 알려드리는 값>"
  }
}

응답

json

{ "key": "user_..." }

Get Student Info

학생 키로 유저 정보를 확인합니다.

http

GET /v1/profile
Authorization: Bearer {USER_KEY}

응답

json

{
  "profile": {
    "user_id": "student@example.com",
    "name": "홍길동",
    "spend": 0.024
  }
}

Revoke Student Key

졸업, 탈퇴, 접근 차단 시 사용합니다.

http

PATCH /v1/keys/{key_id}
Authorization: Bearer {ORG_KEY}

json

{ "is_active": false }

key_id는 발급 시 반환된 키 앞부분입니다. 정확한 형식은 저희 담당자에게 확인해 주세요.

Org Stats

Upcoming

기관 전체의 사용 현황을 조회합니다.

항목	설명
총 학생 수	등록된 user_key 수
총 사용량	기간별 토큰 사용량 합산
활성 학생 수	최근 N일 내 접속한 학생 수
교재별 진도 현황	교재 ID별 수강 완료 비율

http

GET /v1/org/stats?from=2026-01-01&to=2026-03-31
Authorization: Bearer {ORG_KEY}

Student Stats

Upcoming

개별 학생의 학습 활동을 조회합니다.

항목	설명
접속 이력	날짜별 접속 시간
AI 질문 수	대화 턴 수
코드 실행 수	에디터 실행 횟수
강의 진도	수강 완료한 강의 목록
프롬프트 raw 데이터	학생이 AI에게 보낸 메시지 원문 + AI 응답 전체
세션 기간별 요약	접속 세션 단위로 집계한 활동 요약 (질문 수, 실행 수, 소요 시간)

http

# 통계 요약
GET /v1/org/students/{user_id}/stats

# 프롬프트 raw 데이터
GET /v1/org/students/{user_id}/messages?from=2026-01-01&to=2026-03-31

# 세션 기간별 요약
GET /v1/org/students/{user_id}/sessions

Authorization: Bearer {ORG_KEY}

←Curriculum Settings

Integration Request→