API reference

Organization

On this page

This page is generated from the public contract. Descriptions are shown in the original Korean.

Organization 생성·소속·관리자 권한·이메일 초대. 사용·관리는 인증 완료 후 허용합니다.

Organization 생성#

POST /api/organizations

Organization·internal default workspace·생성자 active 소속을 한 트랜잭션에서 만들고 pending으로 생성하며 기존 세션의 현재 Organization 선택을 유지합니다. 세션 쿠키 structly_session이 필요합니다(Bearer 토큰 불가).

Authentication: Session cookie

Parameters

Name	In	Type	Required	Description
`Origin`	header	`string`	Yes	서버 origin(예: http://127.0.0.1:5173)과 같아야 합니다.

Request body

application/json · Required: Yes

Type: OrganizationCreate

Name	Type	Required	Description
`name`	`string`	Yes	앞뒤 공백 제거 후 1~100자. 고유성 없음
`handle`	`string`	Yes	앞뒤 공백 제거·소문자 정규화 후 3~39자. 영문자로 시작하고 영문 소문자·숫자·단일 하이픈만 허용하며 예약어는 거부합니다.

Responses

Status	Description
`201`	성공
`400`	INVALID_REQUEST(query·미정의 필드·JSON 형식·본문 있는 GET/logout)
`401`	UNAUTHENTICATED(세션 없음·만료) 또는 로그인 실패 INVALID_CREDENTIALS. WWW-Authenticate 포함
`403`	FORBIDDEN_ORIGIN(Origin이 서버 origin과 다름·누락)
`405`	METHOD_NOT_ALLOWED. Allow 포함
`409`	ORGANIZATION_HANDLE_CONFLICT
`413`	PAYLOAD_TOO_LARGE(본문 16 KiB 초과)
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED. data에 필드 오류
`500`	INTERNAL_ERROR

201 response body

Type: Organization

Name	Type	Required	Description
`id`	`string`	Yes
`name`	`string`	Yes
`created_at`	`string(date-time)`	Yes
`verification_status`	`string`	Yes	Values: `pending`, `verified`
`verification_source`	`string \| null`	Yes	Values: `migration`, `backoffice`, `null`
`verified_at`	`string(date-time) \| null(date-time)`	Yes
`role`	`string`	Yes	Values: `member`, `admin`
`handle`	`string`	Yes	앞뒤 공백 제거·소문자 정규화 후 3~39자. 예약어·중복은 거부합니다.

Organization 소속 User 목록#

GET /api/organizations/{organization_id}/members

User 세션 전용입니다. Organization 관리자는 active 관리자 소속과 verified 상태를 요구합니다. 초대 토큰은 본문으로만 전달하며 저장·응답·로그에 평문을 남기지 않습니다.

Authentication: Session cookie

Parameters

Name	In	Type	Required	Description
`organization_id`	path	`string`	Yes

Responses

Status	Description
`200`	성공
`400`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`401`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`403`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`404`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`405`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`409`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`410`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`412`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`415`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`422`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`428`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`503`	요청·인증·권한·상태·충돌 또는 발송 설정 오류

200 response body

An array (Member[]). The table lists item fields.

Name	Type	Required	Description
`user_id`	`string`	Yes
`email`	`string`	Yes
`display_name`	`string`	Yes
`state`	`string`	Yes	Values: `active`, `ended`
`role`	`string`	Yes	Values: `member`, `admin`
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

Organization 소속 User 단건#

GET /api/organizations/{organization_id}/members/{id}

Authentication: Session cookie

Parameters

Name	In	Type	Required	Description
`organization_id`	path	`string`	Yes
`id`	path	`string`	Yes

Responses

Status	Description
`200`	성공
`400`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`401`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`403`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`404`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`405`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`409`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`410`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`412`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`415`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`422`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`428`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`503`	요청·인증·권한·상태·충돌 또는 발송 설정 오류

200 response body

Type: Member

Name	Type	Required	Description
`user_id`	`string`	Yes
`email`	`string`	Yes
`display_name`	`string`	Yes
`state`	`string`	Yes	Values: `active`, `ended`
`role`	`string`	Yes	Values: `member`, `admin`
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

소속 상태 또는 관리자 권한 변경#

PATCH /api/organizations/{organization_id}/members/{id}

Authentication: Session cookie

Parameters

Name	In	Type	Required
`organization_id`	path	`string`	Yes
`id`	path	`string`	Yes
`If-Match`	header	`string`	Yes
`Origin`	header	`string`	Yes

Request body

application/json · Required: Yes

Type: MemberChange

No top-level fields to show.

Responses

Status	Description
`200`	성공
`400`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`401`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`403`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`404`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`405`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`409`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`410`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`412`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`415`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`422`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`428`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`503`	요청·인증·권한·상태·충돌 또는 발송 설정 오류

200 response body

Type: Member

Name	Type	Required	Description
`user_id`	`string`	Yes
`email`	`string`	Yes
`display_name`	`string`	Yes
`state`	`string`	Yes	Values: `active`, `ended`
`role`	`string`	Yes	Values: `member`, `admin`
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

Organization 초대 목록#

GET /api/organizations/{organization_id}/invitations

Authentication: Session cookie

Parameters

Name	In	Type	Required	Description
`organization_id`	path	`string`	Yes

Responses

Status	Description
`200`	성공
`400`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`401`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`403`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`404`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`405`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`409`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`410`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`412`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`415`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`422`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`428`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`503`	요청·인증·권한·상태·충돌 또는 발송 설정 오류

200 response body

An array (Invitation[]). The table lists item fields.

Name	Type	Required	Description
`id`	`string`	Yes
`organization_id`	`string`	Yes
`organization_name`	`string`	Yes
`email`	`string`	Yes
`role`	`string`	Yes	Values: `member`, `admin`
`state`	`string`	Yes	Values: `pending`, `expired`, `accepted`, `canceled`
`delivery`	`string`	Yes	Values: `unknown`, `sent`
`expires_at`	`string(date-time)`	Yes
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

이메일 초대 발송#

POST /api/organizations/{organization_id}/invitations

Authentication: Session cookie

Parameters

Name	In	Type	Required	Description
`organization_id`	path	`string`	Yes
`Origin`	header	`string`	Yes

Request body

application/json · Required: Yes

Type: InvitationCreate

Name	Type	Required	Description
`email`	`string`	Yes
`role`	`string`	Yes	Values: `member`, `admin`

Responses

Status	Description
`201`	성공
`400`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`401`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`403`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`404`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`405`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`409`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`410`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`412`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`415`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`422`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`428`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`503`	요청·인증·권한·상태·충돌 또는 발송 설정 오류

201 response body

Type: Invitation

Name	Type	Required	Description
`id`	`string`	Yes
`organization_id`	`string`	Yes
`organization_name`	`string`	Yes
`email`	`string`	Yes
`role`	`string`	Yes	Values: `member`, `admin`
`state`	`string`	Yes	Values: `pending`, `expired`, `accepted`, `canceled`
`delivery`	`string`	Yes	Values: `unknown`, `sent`
`expires_at`	`string(date-time)`	Yes
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

초대 단건#

GET /api/organizations/{organization_id}/invitations/{id}

Authentication: Session cookie

Parameters

Name	In	Type	Required	Description
`organization_id`	path	`string`	Yes
`id`	path	`string`	Yes

Responses

Status	Description
`200`	성공
`400`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`401`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`403`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`404`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`405`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`409`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`410`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`412`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`415`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`422`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`428`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`503`	요청·인증·권한·상태·충돌 또는 발송 설정 오류

200 response body

Type: Invitation

Name	Type	Required	Description
`id`	`string`	Yes
`organization_id`	`string`	Yes
`organization_name`	`string`	Yes
`email`	`string`	Yes
`role`	`string`	Yes	Values: `member`, `admin`
`state`	`string`	Yes	Values: `pending`, `expired`, `accepted`, `canceled`
`delivery`	`string`	Yes	Values: `unknown`, `sent`
`expires_at`	`string(date-time)`	Yes
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

초대 취소#

DELETE /api/organizations/{organization_id}/invitations/{id}

Authentication: Session cookie

Parameters

Name	In	Type	Required
`organization_id`	path	`string`	Yes
`id`	path	`string`	Yes
`If-Match`	header	`string`	Yes
`Origin`	header	`string`	Yes

Responses

Status	Description
`200`	성공
`400`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`401`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`403`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`404`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`405`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`409`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`410`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`412`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`415`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`422`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`428`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`503`	요청·인증·권한·상태·충돌 또는 발송 설정 오류

200 response body

Type: Invitation

Name	Type	Required	Description
`id`	`string`	Yes
`organization_id`	`string`	Yes
`organization_name`	`string`	Yes
`email`	`string`	Yes
`role`	`string`	Yes	Values: `member`, `admin`
`state`	`string`	Yes	Values: `pending`, `expired`, `accepted`, `canceled`
`delivery`	`string`	Yes	Values: `unknown`, `sent`
`expires_at`	`string(date-time)`	Yes
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

초대 재발송·이전 링크 무효화#

POST /api/organizations/{organization_id}/invitations/{id}/resend

Authentication: Session cookie

Parameters

Name	In	Type	Required
`organization_id`	path	`string`	Yes
`id`	path	`string`	Yes
`If-Match`	header	`string`	Yes
`Origin`	header	`string`	Yes

Responses

Status	Description
`200`	성공
`400`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`401`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`403`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`404`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`405`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`409`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`410`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`412`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`415`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`422`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`428`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`503`	요청·인증·권한·상태·충돌 또는 발송 설정 오류

200 response body

Type: Invitation

Name	Type	Required	Description
`id`	`string`	Yes
`organization_id`	`string`	Yes
`organization_name`	`string`	Yes
`email`	`string`	Yes
`role`	`string`	Yes	Values: `member`, `admin`
`state`	`string`	Yes	Values: `pending`, `expired`, `accepted`, `canceled`
`delivery`	`string`	Yes	Values: `unknown`, `sent`
`expires_at`	`string(date-time)`	Yes
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

초대받은 이메일 User의 수락 전 확인#

POST /api/invitations/preview

Authentication: Session cookie

Parameters

Name	In	Type	Required	Description
`Origin`	header	`string`	Yes

Request body

application/json · Required: Yes

Type: InvitationToken

Name	Type	Required	Description
`token`	`string`	Yes

Responses

Status	Description
`200`	성공
`400`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`401`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`403`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`404`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`405`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`409`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`410`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`412`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`415`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`422`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`428`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`503`	요청·인증·권한·상태·충돌 또는 발송 설정 오류

200 response body

Type: Invitation

Name	Type	Required	Description
`id`	`string`	Yes
`organization_id`	`string`	Yes
`organization_name`	`string`	Yes
`email`	`string`	Yes
`role`	`string`	Yes	Values: `member`, `admin`
`state`	`string`	Yes	Values: `pending`, `expired`, `accepted`, `canceled`
`delivery`	`string`	Yes	Values: `unknown`, `sent`
`expires_at`	`string(date-time)`	Yes
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

초대 수락·소속 생성 또는 복구#

POST /api/invitations/accept

Authentication: Session cookie

Parameters

Name	In	Type	Required	Description
`Origin`	header	`string`	Yes

Request body

application/json · Required: Yes

Type: InvitationToken

Name	Type	Required	Description
`token`	`string`	Yes

Responses

Status	Description
`200`	성공
`400`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`401`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`403`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`404`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`405`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`409`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`410`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`412`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`415`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`422`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`428`	요청·인증·권한·상태·충돌 또는 발송 설정 오류
`503`	요청·인증·권한·상태·충돌 또는 발송 설정 오류

200 response body

Type: Member

Name	Type	Required	Description
`user_id`	`string`	Yes
`email`	`string`	Yes
`display_name`	`string`	Yes
`state`	`string`	Yes	Values: `active`, `ended`
`role`	`string`	Yes	Values: `member`, `admin`
`created_at`	`string(date-time)`	Yes
`updated_at`	`string(date-time)`	Yes

Organization handle 사용 가능 여부 조회#

GET /api/organization-handles/{handle}

로그인한 User에게 handle 정규화 결과와 사용 가능 여부만 반환합니다. Organization의 이름·자산·ID는 반환하지 않습니다.

Authentication: Session cookie

Parameters

Name	In	Type	Required	Description
`handle`	path	`string`	Yes

Responses

Status	Description
`200`	성공
`400`	INVALID_REQUEST(query·미정의 필드·JSON 형식·본문 있는 GET/logout)
`401`	UNAUTHENTICATED(세션 없음·만료) 또는 로그인 실패 INVALID_CREDENTIALS. WWW-Authenticate 포함
`403`	FORBIDDEN_ORIGIN(Origin이 서버 origin과 다름·누락)
`405`	METHOD_NOT_ALLOWED. Allow 포함
`422`	VALIDATION_FAILED. data에 필드 오류
`500`	INTERNAL_ERROR

200 response body

Type: OrganizationHandleAvailability

Name	Type	Required	Description
`handle`	`string`	Yes	앞뒤 공백 제거·소문자 정규화 후 3~39자. 예약어·중복은 거부합니다.
`available`	`boolean`	Yes

Organization handle 조회#

GET /api/organizations/{id}/handle

인증 완료 Organization의 active 관리자만 사용합니다. 내부 Organization ID로 지정합니다.

Authentication: Session cookie

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes

Responses

Status	Description
`200`	성공
`400`	INVALID_REQUEST(query·미정의 필드·JSON 형식·본문 있는 GET/logout)
`401`	UNAUTHENTICATED(세션 없음·만료) 또는 로그인 실패 INVALID_CREDENTIALS. WWW-Authenticate 포함
`403`	FORBIDDEN_ORIGIN(Origin이 서버 origin과 다름·누락)
`404`	ORGANIZATION_NOT_FOUND(active 소속이 아닌 Organization)
`405`	METHOD_NOT_ALLOWED. Allow 포함
`422`	VALIDATION_FAILED. data에 필드 오류
`500`	INTERNAL_ERROR

200 response body

Type: OrganizationHandle

Name	Type	Required	Description
`handle`	`string`	Yes	앞뒤 공백 제거·소문자 정규화 후 3~39자. 예약어·중복은 거부합니다.

Organization handle 변경#

PATCH /api/organizations/{id}/handle

인증 완료 Organization의 active 관리자만 사용합니다. 내부 Organization ID로 지정합니다. 변경 시 이전 handle은 즉시 재사용할 수 있으며 별칭·자동 이동을 제공하지 않습니다.

Authentication: Session cookie

Parameters

Name	In	Type	Required	Description
`id`	path	`string`	Yes
`Origin`	header	`string`	Yes	서버 origin(예: http://127.0.0.1:5173)과 같아야 합니다.
`If-Match`	header	`string`	Yes

Request body

application/json · Required: Yes

Type: OrganizationHandleInput

Name	Type	Required	Description
`handle`	`string`	Yes	앞뒤 공백 제거·소문자 정규화 후 3~39자. 영문자로 시작하고 영문 소문자·숫자·단일 하이픈만 허용하며 예약어는 거부합니다.

Responses

Status	Description
`200`	성공
`400`	INVALID_REQUEST(query·미정의 필드·JSON 형식·본문 있는 GET/logout)
`401`	UNAUTHENTICATED(세션 없음·만료) 또는 로그인 실패 INVALID_CREDENTIALS. WWW-Authenticate 포함
`403`	FORBIDDEN_ORIGIN(Origin이 서버 origin과 다름·누락)
`404`	ORGANIZATION_NOT_FOUND(active 소속이 아닌 Organization)
`405`	METHOD_NOT_ALLOWED. Allow 포함
`409`	ORGANIZATION_HANDLE_CONFLICT
`412`	PRECONDITION_FAILED
`413`	PAYLOAD_TOO_LARGE(본문 1 KiB 초과)
`415`	UNSUPPORTED_MEDIA_TYPE
`422`	VALIDATION_FAILED. data에 필드 오류
`428`	PRECONDITION_REQUIRED
`500`	INTERNAL_ERROR

200 response body

Type: OrganizationHandle

Name	Type	Required	Description
`handle`	`string`	Yes	앞뒤 공백 제거·소문자 정규화 후 3~39자. 예약어·중복은 거부합니다.