키의 동작 방식
키는 하나의 회사에 연결되며 고유한 권한 범위(scope) 목록을 가집니다. Alforse는 모든 요청을 두 가지 제한에 대해 동시에 인가하며, 둘 다 허용하는 경우에만 요청이 성공합니다.- 키에 저장된 범위
- 그 시점에 키 생성자가 보유한 권한
키가 필요한 경우와 필요하지 않은 경우
두 방식의 자세한 내용은 인증(Authentication)을 참조하십시오.
키 생성
- 설정 → API 키로 이동하여 신규 API 키를 선택합니다.
- 이름을 입력합니다. 회사 내에서 고유해야 합니다.
- 필요한 경우 만료 시간을 설정합니다. 비워 두면 만료되지 않는 키가 됩니다.
- 연동에 필요한 범위를 부여하고 저장합니다.
- 대화상자에서 즉시 키를 복사합니다. 같은 대화상자에서 MCP 연결 명령도 확인할 수 있습니다.
API 호출
모든 작업은https://api.alforse.com의 /api/v1/{module}/{operation}에 대한 POST 요청이며, 키는 Authorization 헤더에 베어러 토큰으로 전달합니다.
권한, 플랜, 요청 제한
범위
각 범위는sales_view, inventory_create처럼 module_action 형식으로 표기합니다. 연동에서 사용하는 범위만 부여하십시오. 범위가 하나도 없는 키는 인증은 통과하지만 데이터를 읽거나 쓸 수 없습니다. 범위 수정과 키 삭제는 바로 다음 요청부터 적용됩니다.
플랜
키는 Business 또는 파트너(Partner) 플랜의 회사에서만 동작합니다(기능API_KEYS). Starter 플랜에서는 키에 어떤 범위가 있든 모든 요청에 403이 반환됩니다.
요청 제한
앱에는 제한을 설정하는 항목이 없습니다. 연동에서 더 높은 값이 꼭 필요하다면 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) 정책으로 제한됩니다.API 키와 웹훅
이 두 기능은 서로 반대 방향의 트래픽을 처리하며, 어느 쪽도 상대에 의존하지 않습니다.
대부분의 연동은 두 기능을 함께 사용합니다. 웹훅이 변경 사실을 알리면, 연동은 키를 사용하여 최신 레코드를 읽습니다.