인증

모든 Archyl API 요청은 API 키를 사용한 인증이 필요합니다. 이 가이드에서는 API 키를 생성하고 사용하는 방법을 설명합니다.

API 키 생성

Archyl 계정에 로그인합니다
프로필 > API 키로 이동합니다
API 키 생성을 클릭합니다
키를 설정합니다:
- 이름: 설명적인 이름 (예: "CI/CD 파이프라인", "로컬 개발")
- 권한: 읽기 전용 또는 읽기-쓰기
- 만료일: 선택적 만료 날짜
생성을 클릭합니다
즉시 키를 복사하여 저장하세요 - 다시 표시되지 않습니다

API 키 권한

권한	기능
읽기	프로젝트, 요소, 문서 및 아키텍처 데이터 조회
쓰기	프로젝트, 요소 및 문서의 생성, 수정, 삭제

사용 목적에 필요한 최소 권한을 선택하세요.

API 키 사용

모든 요청에 X-API-Key 헤더에 API 키를 포함하세요:

curl -H "X-API-Key: your-api-key" \
  https://api.archyl.com/api/v1/projects

예시: 프로젝트 목록 조회

curl -X GET \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  https://api.archyl.com/api/v1/projects

예시: 시스템 생성

curl -X POST \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Service",
    "description": "Handles payment processing",
    "type": "internal"
  }' \
  https://api.archyl.com/api/v1/projects/{projectId}/systems

MCP 서버 인증

AI 어시스턴트와 함께 MCP 서버를 사용할 때도 동일한 방식으로 인증합니다:

Claude Code / Claude Desktop

MCP 설정에 API 키를 추가하세요:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Cursor

.cursor/mcp.json에서:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/sse",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

보안 모범 사례

키 보호

API 키를 버전 관리에 커밋하지 마세요
CI/CD 파이프라인에서 환경 변수를 사용하세요
주기적으로 키를 교체하세요
환경별로 별도의 키를 사용하세요

환경 변수

# .env에 저장 (.gitignore에 추가)
ARCHYL_API_KEY=your-api-key

# 스크립트에서 사용
curl -H "X-API-Key: $ARCHYL_API_KEY" \
  https://api.archyl.com/api/v1/projects

CI/CD 통합

CI/CD 플랫폼에 API 키를 시크릿으로 저장하세요:

GitHub Actions:

- name: Update Architecture
  env:
    ARCHYL_API_KEY: ${{ secrets.ARCHYL_API_KEY }}
  run: |
    curl -X POST \
      -H "X-API-Key: $ARCHYL_API_KEY" \
      https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

GitLab CI:

update-architecture:
  script:
    - curl -X POST -H "X-API-Key: $ARCHYL_API_KEY" https://api.archyl.com/api/v1/projects/$PROJECT_ID/discover

API 키 관리

키 조회

프로필 > API 키에서 활성 키를 확인할 수 있습니다:

키 이름 및 생성 날짜
권한 수준
만료 상태
마지막 사용 시간

키 폐기

손상되었거나 사용하지 않는 키를 폐기하려면:

프로필 > API 키로 이동합니다
폐기할 키를 찾습니다
폐기를 클릭합니다
작업을 확인합니다

폐기된 키는 즉시 무효화됩니다.

키 만료

키에 만료를 설정할 수 있습니다:

만료 없음: 수동으로 폐기할 때까지 유효
30일: 임시 접근에 적합
90일: 보안과 편의의 균형
사용자 지정: 원하는 만료 날짜 설정

오류 응답

유효하지 않거나 누락된 키

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

HTTP 상태: 401 Unauthorized

권한 부족

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key does not have write permissions"
  }
}

HTTP 상태: 403 Forbidden

만료된 키

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key has expired"
  }
}