> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alforse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API 키

> 스크립트, CI 작업 또는 AI 코딩 클라이언트가 부여된 권한만으로 Alforse API를 호출할 수 있도록 회사 범위의 비밀 키를 생성합니다.

API 키를 사용하면 사람이 로그인하지 않고도 프로그램이 Alforse를 호출할 수 있습니다. 관리자와 개발자는 브라우저 로그인을 완료할 수 없는 스크립트, CI 파이프라인, AI 코딩 클라이언트용 키를 생성합니다. 모든 키는 **설정 → API 키**에서 관리합니다.

## 키의 동작 방식

키는 하나의 회사에 연결되며 고유한 권한 범위(scope) 목록을 가집니다. Alforse는 모든 요청을 두 가지 제한에 대해 동시에 인가하며, 둘 다 허용하는 경우에만 요청이 성공합니다.

* 키에 저장된 범위
* 그 시점에 키 생성자가 보유한 권한

따라서 키는 생성자의 권한을 넘어설 수 없습니다. 생성자에게서 권한을 제거하면 키도 그 권한을 잃습니다. 다른 회사의 데이터에는 항상 접근할 수 없습니다.

### 키가 필요한 경우와 필요하지 않은 경우

| 클라이언트 | 연결 방식 |
| - | - |
| Claude.ai, Claude Desktop, ChatGPT | **OAuth**. 연결은 인가한 사용자의 역할과 회사를 그대로 따르므로 키가 필요하지 않습니다. |
| Claude Code, Cursor, VS Code, Codex | API 키 |
| 헤드리스 스크립트 및 CI | API 키 |
| stdio 전용 클라이언트 | API 키, `mcp-remote`를 통해 연결 |

두 방식의 자세한 내용은 인증(Authentication)을 참조하십시오.

## 키 생성

Alforse screenshot**설정 → API 키: 마스킹된 미리보기, 범위, 요청 제한이 표시된 키 목록과 일회성 대화상자 'You can only see this key once'**

전체 키는 생성 시 단 한 번만 표시됩니다.

1. **설정 → API 키**로 이동하여 **신규 API 키**를 선택합니다.
2. **이름**을 입력합니다. 회사 내에서 고유해야 합니다.
3. 필요한 경우 **만료 시간**을 설정합니다. 비워 두면 만료되지 않는 키가 됩니다.
4. 연동에 필요한 범위를 부여하고 저장합니다.
5. 대화상자에서 즉시 키를 복사합니다. 같은 대화상자에서 MCP 연결 명령도 확인할 수 있습니다.

이 대화상자가 전체 키가 표시되는 유일한 곳입니다. 이후 Alforse는 원본 값을 폐기하고 SHA-256 해시와 목록에 표시할 다섯 글자 미리보기만 보관합니다. 원본을 복구할 수 없으므로 분실한 키는 삭제한 뒤 새로 생성해야 합니다.

HEADS UP

**키를 비밀번호처럼 취급하십시오**

키는 소지자 비밀 값(bearer secret)입니다. 키를 가진 사람은 누구든 해당 범위 안에서 동작할 수 있습니다. 키는 시크릿 관리자에 보관하고 소스 관리에 절대 커밋하지 마십시오. 유출된 경우 키를 삭제하고 새 키를 생성하여 교체하십시오.

## API 호출

모든 작업은 `https://api.alforse.com`의 `/api/v1/{module}/{operation}`에 대한 `POST` 요청이며, 키는 `Authorization` 헤더에 베어러 토큰으로 전달합니다.

```http theme={null}
POST /api/v1/{module}/{operation}
Host: api.alforse.com
Authorization: Bearer alf_your_key_here
Content-Type: application/json
```

그 외에 필요한 것은 없습니다. 키에는 열어야 할 세션도 갱신해야 할 토큰도 없습니다. 요청이 도착하면 Alforse는 제시된 키를 해시하고, 같은 해시를 가진 저장된 레코드를 찾아 키가 만료되지 않았고 요청 제한에도 도달하지 않았는지 확인합니다. 그런 다음에야 작업이 실행됩니다.

NOTE

**허용되는 헤더**

`Authorization: Bearer alf_…`를 사용하십시오. 호환성을 위해 Alforse는 `alforse-key` 헤더에서도 키를 읽습니다. API v1은 `alf_` 키가 아닌 모든 자격 증명을 거부합니다. OAuth 커넥터는 API v1이 아니라 MCP 엔드포인트와 통신합니다.

## 권한, 플랜, 요청 제한

### 범위

각 범위는 `sales_view`, `inventory_create`처럼 `module_action` 형식으로 표기합니다. 연동에서 사용하는 범위만 부여하십시오. 범위가 하나도 없는 키는 인증은 통과하지만 데이터를 읽거나 쓸 수 없습니다. 범위 수정과 키 삭제는 바로 다음 요청부터 적용됩니다.

### 플랜

키는 **Business** 또는 **파트너**(Partner) 플랜의 회사에서만 동작합니다(기능 `API_KEYS`). Starter 플랜에서는 키에 어떤 범위가 있든 모든 요청에 `403`이 반환됩니다.

### 요청 제한

| 설정 | 값 |
| - | - |
| 신규 키 기본값 | **분당 60건 요청**(윈도우 `1m`) |
| 플랫폼 정책이 설정할 수 있는 다른 윈도우 | `1h`, `1d` |
| 집계 단위 | 키별 |
| 확인 위치 | 키 목록의 **요청 제한** 열 |

앱에는 제한을 설정하는 항목이 없습니다. 연동에서 더 높은 값이 꼭 필요하다면 Alforse 지원팀에 문의하십시오. 키가 제한을 초과하면 요청에 `Retry-After` 및 `X-RateLimit-*` 헤더와 함께 `429`("Rate limit exceeded", 요청 제한 초과)가 반환됩니다. `Retry-After` 간격만큼 기다린 뒤 요청을 다시 보내십시오.

## API 선택

키로는 두 가지 인터페이스를 사용할 수 있습니다. 먼저 Alforse API를 사용하고, Alforse API가 제공하지 않는 작업에 한해 Data API를 사용하십시오.

### Alforse API(권장)

Alforse API 호출은 서비스 계층을 거칩니다. 이 계층은 입력을 검증하고, 권한을 적용하며, 변경이 영향을 미치는 파생 데이터를 갱신합니다.

* **동일한 작업, 두 가지 전송 방식.** 하나의 작업은 HTTP(`POST /api/v1/{module}/{operation}`)와 MCP에서 동일한 인수를 받습니다.
* **위험도 라벨.** 모든 작업에는 `READ`, `WRITE`, `DESTRUCTIVE` 태그가 붙어 있어, 클라이언트가 위험도가 높은 작업 전에 확인을 요청할 수 있습니다.
* **레퍼런스와 SDK.** API 레퍼런스에는 예제와 클라이언트 SDK 생성을 위한 OpenAPI 사양이 포함되어 있습니다.

### Data API

Data API는 테이블과 뷰를 REST로 직접 노출합니다. 키가 여기서 볼 수 있는 범위는 앱의 행 수준 보안(row-level security) 정책으로 제한됩니다.

HEADS UP

**Data API 쓰기는 서비스 계층을 거치지 않습니다**

직접 쓰기는 합계, 상태, 원장 항목 같은 파생 값을 다시 계산하지 않습니다. Alforse API에 해당하는 작업이 없고 변경이 영향을 미치는 모든 레코드를 파악하고 있는 경우에만 Data API로 쓰십시오.

## API 키와 웹훅

이 두 기능은 서로 반대 방향의 트래픽을 처리하며, 어느 쪽도 상대에 의존하지 않습니다.

| | 방향 | 사용하는 비밀 값 |
| - | - | - |
| **API 키** | 사용자 시스템이 Alforse를 호출 | 키 자체 |
| **[웹훅](https://docs.alforse.com/ko/docs/building/webhooks.md)** | 구독한 레코드가 변경되면 Alforse가 사용자 시스템을 호출 | 웹훅 고유의 서명 비밀 값(API 키는 사용하지 않음) |

대부분의 연동은 두 기능을 함께 사용합니다. 웹훅이 변경 사실을 알리면, 연동은 키를 사용하여 최신 레코드를 읽습니다.

## 관련 문서

**웹훅**

레코드가 변경되면 알림을 받고, 키로 해당 레코드를 읽습니다.

[Open](https://docs.alforse.com/ko/docs/building/webhooks.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.