애플리케이션

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

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

인증과 권한#

로그인한 세션 또는 개인 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 토큰을 사용합니다.

애플리케이션 목록 조회#

요청#

GET /api/iam/applications/

쿼리 매개변수#

응답#

200 OK와 함께 페이지 번호 기반 페이지네이션 형식으로 반환합니다. 예제에는 애플리케이션 필드 일부만 표시했습니다.

{
  "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}
    }
  ]
}

예제#

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

애플리케이션 필드#

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

애플리케이션 생성#

요청#

POST /api/iam/applications/

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

요청 본문#

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

응답#

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

예제#

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"}'

애플리케이션 상세 조회#

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

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

애플리케이션 수정#

요청#

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

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

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

예제#

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}'

서버 계정 연결과 해제#

요청#

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

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

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

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

응답#

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

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

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

애플리케이션 삭제#

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

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

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

오류 응답#

코드가 포함된 오류 형식은 오류 메시지를 참고하세요.