---
title: "애플리케이션"
description: "Alpacon API로 애플리케이션을 만들고 관리합니다. 생성·조회·수정·삭제 요청, 서버 계정 설정과 연결, 호출자별 권한과 조회 가능한 필드, 플랜 한도와 오류를 확인하세요. 생성할 때 지정할 수 없는 필드와 애플리케이션 삭제가 서비스 토큰에 미치는 영향도 설명합니다."
---

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

# 애플리케이션

**엔드포인트**: `/api/iam/applications/`

애플리케이션은 자동화 작업의 주체입니다. [서비스 토큰](/reference/api/service-tokens/)을 발급하기 전에 애플리케이션을 만드세요. 토큰의 scope는 애플리케이션의 전역 역할이 허용하는 범위 안에 있어야 합니다. 토큰을 만들기 전에 [애플리케이션에 전역 역할을 부여하세요](/reference/api/#3-애플리케이션에-전역-역할-부여).

## 인증과 권한

로그인한 세션 또는 개인 API 토큰으로 호출하세요. 서비스 토큰은 이 API를 호출할 수 없습니다. 개인 API 토큰에는 작업에 맞는 `application:create`, `application:read`, `application:update`, `application:delete` scope가 필요합니다.

인증한 멤버는 누구나 애플리케이션 목록과 상세 정보를 조회할 수 있습니다. 생성에는 `application:create`, 수정과 삭제에는 해당 애플리케이션의 `application:update`와 `application:delete`가 필요합니다. 관리자는 이 권한을 보유하며, 애플리케이션을 만든 사용자는 해당 애플리케이션의 `application:maintainer` 역할을 받습니다. 워크스페이스가 정지된 동안에는 쓰기 요청이 `403 workspace_suspended`를 반환합니다.

예제는 필요한 역할과 scope가 있는 호출자의 개인 API 토큰을 사용합니다.

## 애플리케이션 목록 조회

### 요청

```http
GET /api/iam/applications/
```

### 쿼리 매개변수

| 매개변수 | 유형 | 설명 |
|-----------|------|-------------|
| `name` | string | 이름으로 필터링 |
| `service_type` | string | 서비스 유형으로 필터링 |
| `search` | string | 이름과 설명 검색 |
| `ordering` | string | `name`, `service_type`, `added_at`, `updated_at`. 앞에 `-`를 붙이면 내림차순. 기본값: `name` |
| `page` | integer | 1부터 시작하는 페이지 번호 |
| `page_size` | integer | 페이지당 결과 수. 기본 15, 최대 100 |

### 응답

`200 OK`와 함께 [페이지 번호 기반 페이지네이션](/reference/api/#페이지-나누기) 형식으로 반환합니다. 예제에는 애플리케이션 필드 일부만 표시했습니다.

```json
{
  "count": 1,
  "current": 1,
  "next": null,
  "previous": null,
  "last": 1,
  "results": [
    {
      "id": "9d2e4b71-0c3a-4f5e-8b6d-1a2c3e4f5a6b",
      "name": "CI pipeline",
      "description": "Deployment checks",
      "service_type": "ci_cd",
      "permissions": {"update": true, "delete": true}
    }
  ]
}
```

### 예제

```bash
curl "https://your-workspace.ap1.alpacon.io/api/iam/applications/?service_type=ci_cd" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
```

## 애플리케이션 필드

| 필드 | 유형 | 설명 |
|-------|------|-------------|
| `id` | UUID | 읽기 전용 애플리케이션 ID |
| `name` | string | 필수, 최대 128자. 삭제하지 않은 애플리케이션 사이에서 고유해야 함 |
| `description` | string | 기본값 `""` |
| `service_type` | string | `ai_agent`, `ci_cd`, `monitoring`, `automation`, `integration`, `other`. 기본값 `other`. 용도를 표시하는 값 |
| `created_by` | object | 읽기 전용 생성자 |
| `username` | string / null | 생성 시 지정 불가. 수정 시 다른 주체가 쓰고 있지 않은 유효한 Unix 사용자 이름 필요 |
| `shell` | string | Linux 절대 경로, 최대 32자. 기본값 `/usr/sbin/nologin`. 서버 계정을 만들 때만 적용 |
| `home_directory` | string / null | 절대 경로. null이면 OS 기본값 사용 |
| `provisioning_enabled` | boolean | 기본값 false. 사용자 이름이 필요하므로 생성 시 true로 지정 불가 |
| `auto_provisioning` | boolean | 기본값 false. `provisioning_enabled`가 필요하며, 활성화하면 서버 전반에 계정 생성을 요청 |
| `uid` | integer / null | 1000 이상. 사용자 또는 다른 애플리케이션과 중복 불가 |
| `added_at`, `updated_at` | datetime | 읽기 전용 시각 |
| `permissions` | object | 읽기 전용 권한 정보 `{update, delete}` |

관리자도 애플리케이션 소유자도 아닌 사용자에게는 `username`, `uid`, `shell`, `home_directory`, `provisioning_enabled`, `auto_provisioning`을 반환하지 않습니다. 목록 응답에서는 모든 사용자에게 `shell`과 `home_directory`를 생략합니다.

## 애플리케이션 생성

### 요청

```http
POST /api/iam/applications/
```

`name`과 필요한 선택 필드를 표에 따라 보내세요. `username`은 생성 시 설정할 수 없으므로 보내지 마세요. 계정을 생성하려면 사용자 이름이 필요하므로 이 요청에서 `provisioning_enabled`를 true로 지정할 수 없습니다. 애플리케이션을 만든 뒤 `PATCH`로 사용자 이름과 계정 생성 옵션을 설정하세요.

### 요청 본문

```json
{
  "name": "CI pipeline",
  "description": "Deployment checks",
  "service_type": "ci_cd"
}
```

### 응답

`201 Created`와 함께 애플리케이션 필드를 반환합니다. 워크스페이스 플랜의 애플리케이션 수 한도를 초과하면 `axis: "application"`과 함께 `402 application_limit_exceeded`를 반환합니다. 기본 제공 `alpacon` 애플리케이션은 이 한도에 포함되지 않습니다.

### 예제

```bash
curl -X POST "https://your-workspace.ap1.alpacon.io/api/iam/applications/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI pipeline","description":"Deployment checks","service_type":"ci_cd"}'
```

## 애플리케이션 상세 조회

```http
GET /api/iam/applications/{id}/
```

`id`는 애플리케이션 UUID입니다. `200`과 함께 호출자가 조회할 수 있는 애플리케이션 필드를 반환합니다.

## 애플리케이션 수정

### 요청

```http
PATCH /api/iam/applications/{id}/
PUT /api/iam/applications/{id}/
```

`200`과 함께 수정한 애플리케이션을 반환합니다. `id`, `created_by`, 시각 필드와 `permissions`는 읽기 전용입니다.

`username`을 설정하면 이름이 같고 다른 주체와 연결되지 않은 서버 계정이 연결됩니다. 이름을 바꾸면 이전 이름으로 자동 연결했던 계정의 연결이 해제됩니다. 기존 서버 계정이나 그룹과 이름이 같으면 승인이 필요할 수 있습니다. 이때 `400 approval_superuser_approve_required`를 반환하고 승인 요청을 만듭니다.

### 예제

```bash
curl -X PATCH "https://your-workspace.ap1.alpacon.io/api/iam/applications/9d2e4b71-0c3a-4f5e-8b6d-1a2c3e4f5a6b/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\"" \
  -H "Content-Type: application/json" \
  -d '{"username":"ci-deploy","provisioning_enabled":true}'
```

## 서버 계정 연결과 해제

### 요청

```http
POST /api/iam/applications/{id}/system-users/
POST /api/iam/applications/{id}/system-users/unassign/
```

슈퍼유저 또는 애플리케이션의 유지관리자가 호출할 수 있습니다. 개인 API 토큰을 쓰면 토큰에도 `application:update`가 필요합니다.

두 경로 모두 서버 계정 UUID를 담은 `system_user_ids` 배열을 받습니다. 배열은 비어 있으면 안 되며 중복 ID는 제거됩니다.

```json
{
  "system_user_ids": ["7d3984de-49ab-4cc6-bcdf-21fbd35858b8"]
}
```

### 응답

연결 요청은 `200`과 함께 계정 배열을 반환합니다. 각 계정에는 `id`, `uid`, `username`, `server`, `server_name`, `login_enabled`, `is_pinned`가 포함됩니다. 시스템 계정이나 사용자 또는 다른 애플리케이션에 연결된 계정은 연결할 수 없습니다.

연결 해제 요청은 `200`을 반환합니다.

```json
{
  "unassigned": 1,
  "system_user_ids": ["7d3984de-49ab-4cc6-bcdf-21fbd35858b8"]
}
```

## 애플리케이션 삭제

```http
DELETE /api/iam/applications/{id}/
```

`204 No Content`를 반환합니다. 해당 애플리케이션의 서비스 토큰은 즉시 인증에 쓸 수 없게 되고 토큰 목록에서도 사라집니다. 애플리케이션의 역할은 제거되고 계정 생성은 비활성화되며 서버 계정 연결도 해제됩니다.

```bash
curl -X DELETE "https://your-workspace.ap1.alpacon.io/api/iam/applications/9d2e4b71-0c3a-4f5e-8b6d-1a2c3e4f5a6b/" \
  -H "Authorization: token=\"alpat-xxxxxxxxxxxxxxxxxx\""
```

## 오류 응답

| 상태 | 오류 코드 | 설명 |
|--------|------------|-------------|
| 400 | `unique` | 삭제하지 않은 애플리케이션에서 이미 쓰는 이름 |
| 400 | `application_username_invalid` | 생성 시 사용자 이름을 지정했거나 Unix 사용자 이름이 잘못됨 |
| 400 | `application_username_in_use` | 이미 쓰고 있는 사용자 이름 |
| 400 | `approval_superuser_approve_required` | 이름이 같은 서버 계정 또는 그룹이 있어 승인 필요 |
| 400 | `application_shell_invalid`, `application_home_directory_invalid` | 셸 또는 홈 디렉터리 경로가 잘못됨 |
| 400 | `application_uid_out_of_range`, `application_uid_in_use` | UID가 1000 미만이거나 다른 주체와 중복 |
| 400 | `application_provisioning_username_required` | 사용자 이름 없이 계정 생성 요청 |
| 400 | `application_auto_provisioning_requires_enabled` | 계정 생성이 비활성화된 상태에서 자동 생성 요청 |
| 400 | `application_system_user_not_found` | 요청한 서버 계정이 없음 |
| 400 | `application_system_user_already_bound` | 시스템 계정이거나 다른 주체에 이미 연결된 계정 |
| 401 | `auth_token_missing` | 인증 정보가 없거나 허용되는 인증 정보를 보내지 않음 |
| 402 | `application_limit_exceeded` | 워크스페이스 플랜의 애플리케이션 수 한도 초과 |
| 403 | `api_token_scope_missing`, `rbac_permission_required`, `rbac_object_permission_required` | 토큰 scope 또는 역할 권한 부족 |
| 403 | `workspace_suspended` | 워크스페이스 정지 중 쓰기 요청 거부 |
| 404 | `api_not_found` | 애플리케이션을 찾을 수 없음 |

코드가 포함된 오류 형식은 [오류 메시지](/reference/api/#에러-메시지)를 참고하세요.

Source: https://docs.alpacax.com/ko/reference/api/applications/