CNF API · v1

개요

버전 1은 DNS 관리에서 소유권을 확인한 영역의 DNS 작업을 제공합니다. 토큰은 계정 → API 키에서 생성하고 폐기할 수 있습니다.

기본 URL 및 버전 관리

https://api.c.nf/v1

모든 엔드포인트는 /v1 아래에 있습니다. 호환성을 깨는 변경에는 새 주 버전 경로를 사용합니다. 이전 버전과 호환되는 필드와 엔드포인트는 v1에 추가될 수 있으며 변경 기록에 남습니다.

인증 및 범위

계정 데이터를 읽거나 변경하는 모든 요청에는 Bearer 토큰이 필요합니다. 토큰은 cnf_로 시작하고 32자리 16진수 문자가 이어집니다.

curl https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer cnf_a1b2c3d4e5f60718293a4b5c6d7e8f90"

토큰은 단방향 해시로 저장되며 전체 값은 생성 시 한 번만 표시됩니다. 토큰을 잃어버리면 폐기하고 새 토큰을 만드세요.

각 토큰에는 범위가 있습니다. 범위가 설정되지 않은 토큰에는 기본적으로 dns:read가 부여됩니다. 쓰기 범위에는 읽기 권한도 포함됩니다.

범위가 일치하지 않으면 403 forbidden_scope가 반환되며, 진단을 위해 required_scopes와 token_scopes가 모두 포함됩니다.

사용자별 격리

Bearer 토큰 하나는 정확히 하나의 user_id에 연결됩니다. 각 영역 처리기는 읽기나 쓰기 전에 해당 사용자가 확인한 소유권 요청인지 검사합니다. 관리자 우회, 가장 경로 또는 사용자 간 우회 수단은 없습니다.

* 권한이 있는 토큰도 해당 사용자가 확인한 영역에서만 작업할 수 있습니다. 다른 계정의 영역에 접근하면 403 forbidden_zone이 반환됩니다.

응답 구조

성공 응답

{
  "success": true,
  "data": { "zones": [] },
  "request_id": "req_abc123def456abcd"
}

오류 응답

{
  "success": false,
  "error": "forbidden_zone",
  "message": "zone not verified for this account (or does not exist)",
  "request_id": "req_abc123def456abcd",
  "zone": "example.com"
}

request_id는 모든 응답에 포함되며 클라이언트 측 로그에 안전하게 기록할 수 있습니다.

오류 코드

영역 확인

POST /v1/dns/zones로 영역 소유권을 요청하면 서버는 다음 경로 중 하나를 선택합니다.

1. 즉시 확인(method: "auto") — 다른 계정이 해당 영역의 소유권을 요청하지 않은 경우 사용합니다. 소유권 요청은 즉시 확인됩니다. 레코드는 소유자가 등록기관의 NS 위임을 반환된 네임서버로 변경한 후에만 권한을 갖습니다.
2. TXT 확인 — 소유권 요청이 경합하는 경우 사용합니다. 반환된 TXT 값을 _cnfdns-verify.<zone>에 추가한 다음 POST /v1/dns/zones/{zone}/verify를 호출하세요.
3. 기존 NS 확인 — 이전에 대기 중이던 소유권 요청은 verify_method: "ns"를 사용할 수 있습니다. 확인 과정에서는 영역의 실제 NS 응답을 예상 네임서버 집합과 비교합니다.

확인 작업은 멱등성을 보장합니다. 확인된 요청에 대해 반복하면 소유권 요청을 변경하지 않고 verified: true를 반환합니다.

레코드 유형 및 제한

지원되는 레코드 유형

A, AAAA, CNAME, MX, TXT, NS, SRV, CAA, PTR, SPF.

priority는 MX와 SRV에 필요하며 다른 유형에서는 무시됩니다. ttl은 60초에서 2,592,000초 사이여야 합니다.

엔드포인트

공개 유틸리티

계정 없이 쓰는 작고 안정적인 엔드포인트. 시간, 주소, 국가, 환율, 해시.

계정

토큰이 누구의 것이고 무엇을 할 수 있는지.

DNS

도메인을 신청하고 통제권을 증명한 뒤 레코드를 관리합니다.

자격 증명

자격 증명 도구 뒤의 비공개 보관소.

파일

개인 파일 저장소. 목록, 업로드, 편집, 공유, 삭제.

CDN

공유한 파일의 엣지 캐시와 트래픽.

SMS 전달

휴대폰에서 전달된 메시지와 이를 허용하는 키.

정적 사이트

zip을 올리면 사이트가 됩니다.

배포

배포한 폼, 웹훅, 단축 링크 엔드포인트.

도메인

도메인 포트폴리오와 등록 정보.

패키지

릴리스를 게시하고 버전과 다운로드 수를 조회합니다.

WHOIS

도메인 등록 정보. 캐시되어 도메인 도구와 공유됩니다.

AI 에이전트용

에이전트에게는 /v1/ai를 알려주세요. 프롬프트에 그대로 붙여 넣도록 쓴 요약입니다. /v1/ai?format=json은 같은 엔드포인트를 도구 정의로 돌려줍니다. /v1/openapi.json은 완전한 OpenAPI 3.1 계약이고 /llms.txt는 크롤러용 안내입니다. 넷 다 이 페이지와 같은 라우팅 표에서 생성되므로 없는 엔드포인트를 설명할 수 없습니다.

curl https://api.c.nf/v1/ai
curl https://api.c.nf/v1/ai?format=json
curl https://api.c.nf/v1/openapi.json

요청 필드

영역 소유권 요청 만들기

DNS 레코드 만들기

DNS 레코드 수정

예제

curl -H "Authorization: Bearer $CNF_TOKEN" \
  https://api.c.nf/v1/dns/zones

curl -X POST https://api.c.nf/v1/dns/zones \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"zone":"example.com"}'

curl -X POST https://api.c.nf/v1/dns/zones/example.com/verify \
  -H "Authorization: Bearer $CNF_TOKEN"

curl -X POST https://api.c.nf/v1/dns/zones/example.com/records \
  -H "Authorization: Bearer $CNF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type":"A","host":"api","value":"192.0.2.10"}'

빠른 시작

1. dns:write 범위의 API 키를 계정 → API 키에서 만들고 표시될 때 복사합니다.
2. 토큰을 기기의 보호된 환경 변수에 저장합니다.
3. GET /v1/account/me를 호출하여 토큰과 범위를 확인합니다.
4. 영역 소유권을 요청합니다. 응답에서 즉시 확인, TXT 기반 확인, 기존 NS 기반 확인 중 어떤 방식인지 알려 줍니다.
5. DNS 증명이 필요하면 반환된 증명을 설정한 다음 확인 엔드포인트를 호출합니다.
6. 소유권 요청이 확인된 후에만 레코드를 만들고 읽고 수정하거나 삭제합니다.

변경 기록

v1.1.0 — 영역 관리

• 즉시 및 TXT 확인 경로를 포함한 API 기반 영역 소유권 요청을 추가했습니다.
• 단일 영역 상태 및 멱등 확인 엔드포인트를 추가했습니다.
• 레코드를 자동으로 삭제하지 않는 소유권 요청 취소 기능을 추가했습니다.
• 영역 목록에 확인됨, 대기 중, 전체 필터를 추가했습니다.

v1.0.0 — 최초 릴리스

• Bearer 토큰 인증과 사용자별 영역 격리를 추가했습니다.
• 읽기 및 쓰기 범위를 추가했습니다.
• 계정, 영역 목록, 레코드 관리 엔드포인트를 추가했습니다.
• 요청 식별자를 포함한 일관된 응답 구조를 추가했습니다.