관리 API 키 - DGrid AI Docs

Management API Keys는 Model API 키의 전체 생명주기를 프로그래밍 방식으로 관리하는 방법을 제공합니다. 이는 수동 콘솔 작업에 의존하지 않고 키를 생성, 배포, 교체, 활성화, 비활성화 또는 폐기해야 하는 엔터프라이즈 팀, SaaS 플랫폼, 자동화 시스템을 위해 설계되었습니다. Management API Keys는 관리용 자격 증명이며 키 관리 작업으로만 제한됩니다. 모델 추론 또는 완성 엔드포인트를 호출하는 데는 사용할 수 없습니다.

1. 개요

Management API Keys는 다음과 같은 시나리오를 위해 설계되었습니다.

서로 다른 고객, 프로젝트, 환경에 대해 별도의 Model API 키를 발급
하위 Model API 키에 사용량 한도 및 자동 초기화 주기 적용
프로그래밍 방식으로 키를 교체, 비활성화 또는 폐기
SaaS, 멀티 테넌트, 컴플라이언스 중심 워크플로에서 최소 권한 키 관리 시행

핵심 기능:

키 관리 작업에 대한 엄격한 권한 분리
Model API 키에 대한 전체 생명주기 자동화
설정 가능한 사용량 한도 및 초기화 주기
서버 측 서비스, 내부 도구, 자동화된 프로비저닝 워크플로를 위해 설계됨

2. API 영역 및 인증 경계

키 관리는 각기 고유한 인증 모델을 가진 두 개의 API 영역으로 나뉩니다.

API 영역	목적	인증
`/v1/management-keys`	Management API Keys 관리	`JWT`
`/api/v1/model-router/keys`	Management API Key를 사용한 Model API Keys 관리	`Authorization: Bearer <management_key>`

중요 사항:

Management API Key는 /api/v1/model-router/keys에서만 사용할 수 있습니다
Management API Key는 /v1/management-keys에서 사용할 수 없습니다
/v1/management-keys는 JWT 인증만 지원합니다
전체 시크릿은 키가 생성될 때 한 번만 반환되며, 이후에는 다시 조회할 수 없습니다

3. 기본 규칙

각 계정은 최대 10개의 Management API Keys를 생성할 수 있습니다
Management API Keys는 생성 즉시 활성화됩니다
전체 Management API Key 시크릿은 한 번만 반환됩니다
이후의 목록 및 상세 응답에는 마스킹된 키 값만 반환됩니다
Model API Keys는 현재 영구 삭제가 아닌 소프트 삭제 방식으로 처리됩니다

4. Base URL

퍼블릭 API의 base URL은 다음과 같습니다.

https://api.dgrid.ai

이 문서에서 사용되는 경로 접두사:

/v1/management-keys
/api/v1/model-router/keys

5. Management API Key 생성

Management API를 사용하기 전에, 먼저 DGrid 콘솔에서 Management API Key를 생성하세요.

Management API Keys 페이지 열기

Create 클릭

키 이름 입력

필수 보안 인증 완료

생성 즉시 키를 복사하여 안전하게 보관

이 흐름을 자체 UI에서 노출하는 경우, 시크릿이 한 번만 표시되며 즉시 저장해야 함을 사용자에게 명확히 안내하세요.

6. 인증

이 문서는 두 가지 인증 모드를 다룹니다.

/v1/management-keys 하위 엔드포인트는 JWT가 필요합니다
/api/v1/model-router/keys 하위 엔드포인트는 Management API Key가 필요합니다

/api/v1/model-router/keys 엔드포인트를 호출할 때는 다음 헤더를 사용하세요.

Authorization: Bearer <management_key>

7. Management API Key 생명주기 엔드포인트

이 엔드포인트들은 Management API Keys를 생성, 조회, 업데이트, 활성화, 비활성화, 삭제하는 데 사용됩니다. 모두 JWT 인증이 필요합니다.

작업	메서드	경로	참고
관리 키 생성	`POST`	`/v1/management-keys`	전체 키는 한 번만 반환됩니다
관리 키 목록 조회	`GET`	`/v1/management-keys`	페이지네이션 지원
관리 키 업데이트	`PUT`	`/v1/management-keys/{id}`	현재는 `name`만 업데이트 가능
관리 키 삭제	`DELETE`	`/v1/management-keys/{id}`	소프트 삭제
관리 키 활성화	`POST`	`/v1/management-keys/{id}/enablement`	즉시 적용됩니다
관리 키 비활성화	`POST`	`/v1/management-keys/{id}/disablement`	즉시 적용됩니다

생성 응답 예시:

{
  "code": 200,
  "message": "ok",
  "data": {
    "id": "3ecf9d8d-9b8f-4df6-9d30-7a693e1f0d1c",
    "name": "prod-admin",
    "key": "mk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "keyPreview": "mk-x************************xxxx5",
    "createdAt": "2026-04-23T10:00:00Z",
    "status": "Enabled",
    "enabled": true
  }
}

참고 사항:

key는 생성 시점에 한 번만 반환됩니다
keyPreview는 마스킹된 표시 값입니다

8. Management API Key로 Model API Keys 관리

이 섹션의 모든 엔드포인트는 다음을 사용합니다.

Authorization: Bearer <management_key>

8.1 요청 필드

현재 구현에서는 Model API Key를 생성하거나 업데이트할 때 다음 필드를 지원합니다.

필드	유형	필수	설명
`name`	`string`	생성 시 필수	키 이름
`limit`	`number`	아니요	사용량 한도
`cycle`	`daily \| weekly \| monthly`	아니요	한도 초기화 주기
`expiredAt`	`string`	아니요	UTC 기준 만료 타임스탬프
`groupId`	`string`	아니요	그룹 ID

참고 사항:

OpenRouter의 limit_reset에 익숙하다면, 현재 DGrid 구현에서 가장 가까운 대응 항목은 cycle입니다
expiredAt은 2026-12-31T23:59:59Z와 같은 ISO 8601 UTC 타임스탬프 형식을 사용해야 합니다

8.2 키 목록 조회

메서드: GET
경로: /api/v1/model-router/keys
쿼리 매개변수:
- page: 페이지 번호, 기본값 1
- size: 페이지 크기, 기본값 20, 최대 100

구현 참고 사항:

페이지네이션은 limit과 offset이 아닌 page와 size를 사용합니다
현재 이름 부분 검색은 지원되지 않습니다
현재 disabled 필터링은 지원되지 않습니다

요청 예시:

curl "https://api.dgrid.ai/api/v1/model-router/keys?page=1&size=20" \
  -H "Authorization: Bearer <management_key>"

응답 예시:

{
  "code": 200,
  "message": "ok",
  "data": {
    "total": 2,
    "page": 1,
    "items": [
      {
        "id": "e8f9c547-4f0c-4d8b-8e1b-8ef9b0aa1111",
        "name": "prod-key",
        "key": "sk-a************************f9x2d",
        "limit": 1000,
        "usageInCycle": 12.34,
        "usageInTotal": 98.76,
        "enabled": true,
        "cycle": "monthly",
        "expiredAt": "2026-12-31T23:59:59Z",
        "groupId": null,
        "groupName": ""
      }
    ]
  }
}

필드 설명:

key: 마스킹된 API 키 값
usageInCycle: 현재 주기 동안의 사용량
usageInTotal: 누적 사용량
enabled: 현재 활성화 상태
groupName: 그룹 이름

8.3 Model API Key 생성

메서드: POST
경로: /api/v1/model-router/keys

요청 예시:

curl -X POST "https://api.dgrid.ai/api/v1/model-router/keys" \
  -H "Authorization: Bearer <management_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-key",
    "limit": 1000,
    "cycle": "monthly",
    "expiredAt": "2026-12-31T23:59:59Z"
  }'

요청 본문 예시:

{
  "name": "prod-key",
  "limit": 1000,
  "cycle": "monthly",
  "expiredAt": "2026-12-31T23:59:59Z"
}

응답 예시:

{
  "code": 200,
  "message": "ok",
  "data": {
    "id": "e8f9c547-4f0c-4d8b-8e1b-8ef9b0aa1111",
    "key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

참고 사항:

key는 전체 API 키 값이며 한 번만 반환됩니다
즉시 안전한 시크릿 관리 시스템에 저장하세요

8.4 키 상세 정보 조회

메서드: GET
경로: /api/v1/model-router/keys/{id}

구현 참고 사항:

현재 구현은 key_hash가 아닌 id (UUID)를 사용합니다

요청 예시:

curl "https://api.dgrid.ai/api/v1/model-router/keys/e8f9c547-4f0c-4d8b-8e1b-8ef9b0aa1111" \
  -H "Authorization: Bearer <management_key>"

응답 예시:

{
  "code": 200,
  "message": "ok",
  "data": {
    "id": "e8f9c547-4f0c-4d8b-8e1b-8ef9b0aa1111",
    "name": "prod-key",
    "key": "sk-a************************f9x2d",
    "limit": 1000,
    "usageInCycle": 12.34,
    "usageInTotal": 98.76,
    "enabled": true,
    "cycle": "monthly",
    "expiredAt": "2026-12-31T23:59:59Z",
    "groupId": null,
    "groupName": ""
  }
}

8.5 Model API Key 업데이트

메서드: PUT
경로: /api/v1/model-router/keys/{id}

현재 지원되는 업데이트 필드:

name
limit
cycle
groupId

요청 예시:

curl -X PUT "https://api.dgrid.ai/api/v1/model-router/keys/e8f9c547-4f0c-4d8b-8e1b-8ef9b0aa1111" \
  -H "Authorization: Bearer <management_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-key-v2",
    "limit": 2000,
    "cycle": "monthly"
  }'

요청 본문 예시:

{
  "name": "prod-key-v2",
  "limit": 2000,
  "cycle": "monthly"
}

구현 참고 사항:

현재 업데이트 메서드는 PATCH가 아닌 PUT입니다

8.6 Model API Key 비활성화

메서드: POST
경로: /api/v1/model-router/keys/{id}/disablement

요청 예시:

curl -X POST "https://api.dgrid.ai/api/v1/model-router/keys/e8f9c547-4f0c-4d8b-8e1b-8ef9b0aa1111/disablement" \
  -H "Authorization: Bearer <management_key>"

비활성화 후에는 해당 API 키를 모델 호출에 사용할 수 없습니다.

8.7 Model API Key 활성화

메서드: POST
경로: /api/v1/model-router/keys/{id}/enablement

요청 예시:

curl -X POST "https://api.dgrid.ai/api/v1/model-router/keys/e8f9c547-4f0c-4d8b-8e1b-8ef9b0aa1111/enablement" \
  -H "Authorization: Bearer <management_key>"

8.8 Model API Key 삭제

메서드: DELETE
경로: /api/v1/model-router/keys/{id}

요청 예시:

curl -X DELETE "https://api.dgrid.ai/api/v1/model-router/keys/e8f9c547-4f0c-4d8b-8e1b-8ef9b0aa1111" \
  -H "Authorization: Bearer <management_key>"

구현 참고 사항:

삭제는 현재 물리적 삭제가 아닌 소프트 삭제입니다

9. 사용 예시

import requests

BASE = "https://api.dgrid.ai/api/v1/model-router"
MANAGEMENT_KEY = "mk-your-management-key"

headers = {
    "Authorization": f"Bearer {MANAGEMENT_KEY}",
    "Content-Type": "application/json"
}

# 1) List keys
resp = requests.get(
    f"{BASE}/keys",
    headers=headers,
    params={"page": 1, "size": 20}
)
print("LIST:", resp.json())

# 2) Create key
resp = requests.post(
    f"{BASE}/keys",
    headers=headers,
    json={
        "name": "prod-key",
        "limit": 1000,
        "cycle": "monthly",
        "expiredAt": "2026-12-31T23:59:59Z"
    }
)
create_data = resp.json()
print("CREATE:", create_data)

key_id = create_data["data"]["id"]

# 3) Get key
resp = requests.get(f"{BASE}/keys/{key_id}", headers=headers)
print("GET:", resp.json())

# 4) Update key
resp = requests.put(
    f"{BASE}/keys/{key_id}",
    headers=headers,
    json={
        "name": "prod-key-v2",
        "limit": 2000,
        "cycle": "monthly"
    }
)
print("UPDATE:", resp.json())

# 5) Disable key
resp = requests.post(f"{BASE}/keys/{key_id}/disablement", headers=headers)
print("DISABLE:", resp.json())

# 6) Enable key
resp = requests.post(f"{BASE}/keys/{key_id}/enablement", headers=headers)
print("ENABLE:", resp.json())

# 7) Delete key
resp = requests.delete(f"{BASE}/keys/{key_id}", headers=headers)
print("DELETE:", resp.json())

10. HTTP 상태 및 오류 코드

HTTP 상태	오류 코드	설명
`400`	`40001`	잘못된 요청 매개변수
`401`	`40101`	요청 헤더에 Management API Key가 없음
`401`	`40102`	Management API Key가 유효하지 않거나, 만료되었거나, 비활성화됨
`403`	`40301`	이 엔드포인트에 대한 권한이 부족하거나 키 유형이 올바르지 않음
`404`	`40401`	대상 키를 찾을 수 없거나 현재 계정에 속하지 않음
`429`	`42901`	요청 한도 초과
`500`	`50001`	내부 서버 오류

11. 표준 응답 형식

성공적인 응답은 다음과 같은 형식을 사용합니다.

{
  "code": 200,
  "message": "ok",
  "data": {}
}

참고 사항:

성공한 요청은 HTTP 200을 반환합니다
생성 응답에는 data에 전체 시크릿 키가 포함될 수 있습니다
목록 및 상세 엔드포인트는 일반적으로 마스킹된 키 값을 반환합니다
Management API Keys와 Model API Keys 모두의 전체 시크릿은 한 번만 반환됩니다

​1. 개요

​2. API 영역 및 인증 경계

​3. 기본 규칙

​4. Base URL

​5. Management API Key 생성

​6. 인증

​7. Management API Key 생명주기 엔드포인트

​8. Management API Key로 Model API Keys 관리

​8.1 요청 필드

​8.2 키 목록 조회

​8.3 Model API Key 생성

​8.4 키 상세 정보 조회

​8.5 Model API Key 업데이트

​8.6 Model API Key 비활성화

​8.7 Model API Key 활성화

​8.8 Model API Key 삭제

​9. 사용 예시

​10. HTTP 상태 및 오류 코드

​11. 표준 응답 형식

1. 개요

2. API 영역 및 인증 경계

3. 기본 규칙

4. Base URL

5. Management API Key 생성

6. 인증

7. Management API Key 생명주기 엔드포인트

8. Management API Key로 Model API Keys 관리

8.1 요청 필드

8.2 키 목록 조회

8.3 Model API Key 생성

8.4 키 상세 정보 조회

8.5 Model API Key 업데이트

8.6 Model API Key 비활성화

8.7 Model API Key 활성화

8.8 Model API Key 삭제

9. 사용 예시

10. HTTP 상태 및 오류 코드

11. 표준 응답 형식