---
title: "REST API로 자동화하기"
description: "권한 범위를 지정한 서비스 토큰으로 Alpacon REST API에 연결하세요. 서버 목록을 요청하고 페이지별 응답을 읽는 방법을 예제로 설명합니다. 토큰 만료나 접근 거부가 발생했을 때 확인할 필드와 재시도 방법, 필요한 scope를 찾는 위치도 구체적으로 안내합니다."
---

> Full documentation index: https://docs.alpacax.com/llms.ko.txt

# REST API로 자동화하기

애플리케이션이 수행하는 자동화 작업에는 서비스 토큰을 사용합니다. 이 예제에서는 토큰에 접근 권한이 있는 서버 목록을 읽습니다. 요청과 응답 필드는 [서버 API 참조](/reference/api/servers/servers/)를 확인하세요.

## 애플리케이션과 토큰 준비

`server:read` scope를 가진 [애플리케이션과 서비스 토큰](/use/iam/applications/service-tokens/)을 만드세요. 작업에 필요한 서버에만 접근을 허용합니다. 다른 작업에 필요한 scope는 [scope 참조](/reference/scopes/)에서 확인할 수 있습니다. 개인 API 토큰은 소유자의 권한으로 작동하며, 새 토큰에는 명령 실행이나 파일 전송 scope를 부여할 수 없습니다.

서비스 토큰을 안전하게 보관하세요. 승인을 기다리는 토큰은 활성화된 뒤에 요청에 사용합니다. 토큰이 만료되었거나 허용된 IP 또는 시간 범위를 벗어나도 요청이 거부됩니다.

## 인증하기

워크스페이스 URL과 토큰을 `Authorization` 헤더에 넣습니다. 예시 값을 실제 값으로 바꾸세요. `token`은 소문자로 써야 하며 `Bearer` 형식은 사용할 수 없습니다.

```bash
export ALPACON_URL='https://your-workspace.ap1.alpacon.io'
read -r -s -p 'Service token: ' SERVICE_TOKEN
printf '\n'
curl --fail-with-body --silent --show-error \
  "$ALPACON_URL/api/servers/servers/?page_size=15" \
  -H "Authorization: token=\"$SERVICE_TOKEN\""
```

## 응답 읽기

응답의 `results`에 서버가 들어 있고, `next`에는 다음 페이지 번호가 표시됩니다. `next`가 `null`이 될 때까지 해당 페이지를 요청하세요. 페이지 형식과 상태 코드는 [API 개요](/reference/api/#페이지-나누기)를 확인하세요. 일부 서버만 필요하다면 [서버 목록 필터](/reference/api/servers/servers/#서버-목록-조회)를 사용합니다.

명령 실행이나 파일 전송에는 필요한 scope와 접근 규칙을 갖춘 [서비스 토큰](/use/iam/applications/service-tokens/)을 사용하세요. 요청 필드는 [명령 API](/reference/api/commands/) 또는 해당 파일 API 참조를 확인합니다. 토큰의 서버 접근 범위와 명령 또는 파일 규칙도 적용됩니다.

## 만료와 요청 거부 처리

`401` 응답이 오면 토큰의 활성화 상태와 만료 시점, 허용 IP와 시간 범위를 확인하세요. `403`이면 scope나 다른 접근 규칙이 부족할 수 있습니다. 응답에 `code`, `gate`, `missing`이 있다면 해당 필드를 확인합니다. 요청 횟수 제한에는 `Retry-After`를 따르세요. 자동화 분기는 사람이 읽는 `message`나 `hint`가 아닌 구조화된 필드로 판단합니다. 자세한 내용은 [API 거부 응답](/reference/api/#거부-응답)을 확인하세요.

## API로 명령 실행하기

명령 자동화에는 `ci-deploy` 같은 애플리케이션 계정을 만들고, 필요한 명령 scope를 가진 서비스 토큰을 발급하세요. 대상 서버와 실행할 명령 전체를 토큰의 접근 규칙에 허용하고, 이 계정이 배포 디렉터리를 사용할 수 있도록 준비합니다. 다음은 [명령 API](/reference/api/commands/) 예제입니다.

```bash
curl --fail-with-body --silent --show-error \
  -X POST "$ALPACON_URL/api/events/commands/" \
  -H "Authorization: token=\"$SERVICE_TOKEN\"" \
  -H 'Content-Type: application/json' \
  -d '{"server":"7e3984de-49ab-4cc6-bcdf-21fbd35858b8","line":"deploy","username":"ci-deploy","purpose":"Run the approved deployment"}'
```

API가 요청을 받아도 명령은 승인이나 계정 준비를 기다릴 수 있습니다. 명령 기록에서 최종 상태를 확인하세요. 규칙이 명령 전체와 어떻게 일치하는지는 [서비스 토큰 명령 가이드](/use/iam/applications/service-tokens/command-patterns/)를 참고하세요.

같은 작업을 CLI로 실행할 수도 있습니다.

```bash
alpacon exec ci-deploy@production "cd /app && git pull && npm install && pm2 restart"
for server in web1 web2 web3; do
  alpacon exec "ci-deploy@$server" "sudo systemctl restart nginx"
done
```

두 번째 예제에는 `sudo systemctl restart nginx` 전체 명령과 일치하는 규칙이 필요합니다. Alpacon Cloud에서는 워크스페이스 sudo 설정이 허용하는 경우 **서비스 토큰 실행**의 기본 규칙에 따라 위험도가 **심각** 미만인 서비스 토큰 sudo를 허용하지만, 더 엄격한 워크스페이스 규칙이 있으면 거부될 수 있습니다. 기본 설정의 자체 호스팅 환경에서는 서비스 토큰 sudo를 거부합니다. 정확한 판단 조건은 [접근 규칙 참조](/reference/access-rules/)를 확인하세요.

Source: https://docs.alpacax.com/ko/integrate/rest-api/