수락된 워크스페이스 멤버를 조회하고 역할, SCIM 관리 여부, 검색어로 필터링합니다.
워크스페이스 멤버 목록 조회
플랜:
Business 이상
스코프: workspaces:read
수락된 워크스페이스 멤버를 user_id, type, name과 함께 반환합니다. name은 저장된 표시 이름이며 사용할 수 없으면 null입니다. 반복되는 role, scim_managed=true|false, query로 필터링할 수 있습니다. sort_by와 sort_order로 정렬합니다. 검색어가 있으면 기본적으로 가장 잘 맞는 결과가 먼저 오고, 검색어가 없으면 역할 우선순위와 가장 최근 참여 시각순으로 정렬됩니다. 커서는 발급 당시의 필터와 정렬에 고정됩니다. 다른 매개변수와 함께 제시하면 400을 반환합니다. 읽기는 최종적 일관성을 가지므로 최근 변경이 즉시 나타나지 않을 수 있습니다. 예상한 변경이 보이지 않으면 백오프를 두고 다시 읽으세요.
OpenAPI
| 항목 | 값 |
|---|---|
| Method | GET |
| Path | /v1/workspaces/{workspace_id}/members |
| Operation ID | listWorkspaceMembers |
| Source spec | https://api.lovable.dev/v1/openapi.yaml |
| Local snapshot | YAML 스냅샷 (SHA-256: ba9124b3aece607e3f9f6e2a57d317261f3d3ab343674ad112aec0af71133e9a) |
GET /v1/workspaces/{workspace_id}/members인증
Lovable-API-Key: lov_your-api-key 또는 Authorization: Bearer <key>를 보냅니다. 이 엔드포인트는 workspaces:read 스코프가 필요합니다.
매개변수
| 이름 | 위치 | 필수 | 타입 | 설명 |
|---|---|---|---|---|
workspace_id | path | 예 | string | 워크스페이스 ID입니다. |
limit | query | 아니요 | integer, int64 | 페이지당 반환할 최대 항목 수입니다. 기본값은 50, 최솟값은 1, 최댓값은 100입니다. |
cursor | query | 아니요 | string | 이전 응답의 pagination.next_cursor를 전달해 다음 페이지를 가져옵니다. 첫 페이지에서는 생략합니다. 페이지를 따라갈 때 같은 필터와 정렬 순서를 유지하세요. |
query | query | 아니요 | string | 표시 이름, 사용자 이름, 이메일로 검색합니다. 최대 길이는 1000자이며 3자보다 짧은 term은 무시됩니다. |
role | query | 아니요 | string[] | 응답에 반환되는 역할을 기준으로 필터링합니다. enum: workspace_owner, workspace_admin, workspace_editor, workspace_viewer, external_collaborator, owner, admin, editor, member, viewer, collaborator. 앞의 5개는 응답에 반환되는 역할 값이고 나머지 6개는 이전 값입니다. 이전 값은 별칭으로 계속 허용되며 member와 editor는 모두 workspace_editor를 선택합니다. 매개변수를 반복해 여러 값 중 하나와 일치시킬 수 있습니다. 생략하면 모든 역할을 포함합니다. |
sort_by | query | 아니요 | string | 정렬 필드입니다. name, display_name, joined_at, role, relevance 중 하나입니다. 생략하면 기본 정렬은 역할 우선순위(workspace_owner, workspace_admin, workspace_editor, external_collaborator, workspace_viewer)와 최근 참여순입니다. query가 있으면 가장 잘 맞는 결과가 먼저 옵니다. name은 반환된 이름을 대·소문자 구분 없이 정렬하며 null 이름은 오름차순에서 맨 앞, 내림차순에서 맨 뒤에 놓입니다. display_name은 name의 alias이며 정렬 순서가 같고 커서를 서로 바꿔 쓸 수 있습니다. joined_at은 참여 시각이 없으면 초대 시각을 사용합니다. role은 역할 우선순위로 정렬합니다. relevance는 일치 점수로 순위를 매기고 query를 요구하며 동점은 가장 최근 참여순으로 가립니다. 그 밖의 동점은 멤버십 ID로 가립니다. |
sort_order | query | 아니요 | string | sort_by의 방향입니다. asc 또는 desc입니다. 기본값은 내림차순이며 sort_by가 필요합니다. |
scim_managed | query | 아니요 | boolean | SCIM(System for Cross-domain Identity Management) 프로비저닝 여부로 필터링합니다. true는 identity provider가 프로비저닝한 멤버만, false는 다른 방식으로 추가된 멤버만 반환합니다. 생략하면 둘 다 포함합니다. |
Lovable-Version | header | 아니요 | string | 제공받을 안정 API 버전입니다. YYYY-MM-DD 날짜 형식으로 보냅니다. 생략하면 현재 가장 오래된 지원 안정 버전인 2026-09-11이 사용됩니다. |
Lovable-Beta | header | 아니요 | string | 안정 버전 위에 활성화할 베타 리비전 문자열입니다. 여러 개는 쉼표로 구분합니다. |
예시
curl --request GET \
--url 'https://api.lovable.dev/v1/workspaces/workspace-id/members' \
--header 'Lovable-API-Key: lov_your-api-key' \
--header 'Lovable-Version: 2026-09-11'const response = await fetch("https://api.lovable.dev/v1/workspaces/workspace-id/members", {
method: "GET",
headers: {
"Lovable-API-Key": process.env.LOVABLE_API_KEY ?? "lov_your-api-key",
"Lovable-Version": "2026-09-11",
},
});
if (!response.ok) {
throw new Error(`Lovable API ${response.status}: ${await response.text()}`);
}
console.log(await response.json());응답
| 상태 | 본문 | 설명 |
|---|---|---|
200 | WorkspaceMemberPage | 요청이 성공했습니다. |
400 | ErrorResponse | 요청 본문 또는 매개변수 형식이 잘못되었거나 검증에 실패했습니다. |
401 | ErrorResponse | API 키, 세션 토큰 또는 OAuth access token이 없거나 유효하지 않습니다. |
402 | ErrorResponse | Public API 접근에는 Business 이상 플랜이 필요합니다. |
403 | ErrorResponse | 키 또는 호출자에게 필요한 스코프나 권한이 없습니다. |
404 | ErrorResponse | 워크스페이스가 존재하지 않거나 삭제되었거나 자격 증명의 워크스페이스 스코프 밖에 있습니다. |
406 | ErrorResponse | Accept 헤더가 이 엔드포인트가 생성하는 모든 미디어 타입을 제외합니다. |
429 | ErrorResponse | 요청이 너무 많습니다. Retry-After가 있으면 해당 간격 뒤에 재시도합니다. |
503 | ErrorResponse | 서비스를 일시적으로 사용할 수 없거나 처리 기한이 만료되었습니다. |
default | ErrorResponse | 오류입니다. 응답 본문은 표준 오류 envelope을 사용하며 status는 HTTP 상태 코드와 같고 type은 machine-readable 오류 코드입니다. |
오류 요구사항 metadata
이 읽기 작업에서 요구사항 metadata는 402와 403 응답의 props에만 나타납니다. 402 payment_required는 최소 플랜 tier를 담은 required_plan을 주거나, 기능 게이트일 때 required_features 배열을 주며 required_features의 식별자는 '모두' 충족해야 합니다. 두 key는 함께 오지 않으며 그 밖의 결제 실패에서는 둘 다 없을 수 있습니다. 403 forbidden의 required_permissions는 대체 가능한 권한 집합의 배열이고 어느 한 집합의 권한을 '모두' 가지면 통과하므로 'AND 집합들의 OR'로 읽습니다. 403 insufficient_scope의 required_scopes는 허용되는 스코프 목록이며 그중 '아무거나' 하나로 충족됩니다. 이 엔드포인트에서는 workspaces:read가 그 목록에 해당하고 workspaces:write가 이를 포함합니다.
type | props 구조와 의미 |
|---|---|
payment_required | 플랜 게이트는 최소 tier(pro, business, enterprise)를 담은 required_plan을 포함합니다. 기능 게이트는 대신 기능 권한 식별자 배열인 required_features를 포함하며 배열의 모든 항목이 필요합니다. 예를 들어 {"required_plan":"business"}입니다. 다른 결제 실패는 둘 다 없을 수 있습니다. |
forbidden | 권한 게이트는 대체 가능한 권한 집합의 배열인 required_permissions를 포함합니다. 한 집합의 권한을 모두 가지면 그 게이트를 충족합니다. 예를 들어 [["project:edit"]]는 해당 권한을 요구하고 [["a","b"],["c"]]는 a와 b를 모두 가지거나 c를 가질 것을 요구합니다. 다른 거부에는 요구사항 metadata가 없을 수 있습니다. |
insufficient_scope | required_scopes는 허용되는 자격 증명 스코프의 배열이며 그중 하나만 있으면 실패한 스코프 검사를 충족합니다. 쓰기 스코프는 대응하는 읽기 스코프도 포함합니다. 예를 들어 {"required_scopes":["projects:write"]}입니다. |
security_critical_findings | finding_refs는 게시를 막는 보안 발견 항목을 식별하는 문자열 배열입니다. 예를 들어 {"finding_refs":["supabase/finding-1"]}입니다. |
retired_version, retired_beta | migration_url은 마이그레이션 가이드로 연결되는 문자열 URL이며 제공 가능한 경우에만 포함됩니다. |
요구사항 metadata는 실패한 검사만 설명하며 작업의 모든 조건을 설명하지 않습니다. 다른 검사가 여전히 요청을 거부할 수 있고 metadata 자체가 생략될 수도 있습니다. 권한·기능 식별자는 실질적 접근 범위를 설명하며 필요한 워크스페이스 역할을 확정하지 않으므로 접근 권한이 필요하면 워크스페이스 관리자에게 문의하세요. 식별자는 시간이 지나며 추가될 수 있습니다. 내부 전용 요구사항과 리소스를 감추는 응답은 접근 요구사항을 공개하지 않습니다.
응답 헤더
모든 응답에는 상황에 따라 다음 공통 헤더가 포함될 수 있습니다: Lovable-Version, Lovable-Beta, X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-Lovable-Unknown-Query-Params, X-Lovable-Unknown-Query-Params-Omitted. X-Lovable-Unknown-Query-Params는 이 작업이 선언하지 않은 query parameter가 있을 때 URL escape된 이름을 최대 20개까지 쉼표로 제공하며, 20개를 넘으면 X-Lovable-Unknown-Query-Params-Omitted가 누락된 개수(minimum: 1)를 제공합니다. 401 응답은 string인 WWW-Authenticate를, 429 응답은 integer인 Retry-After를 포함합니다. Retry-After는 minimum: 1입니다. X-RateLimit-Reset은 지연 시간이 아니라 Unix timestamp 초 단위입니다.
스키마
WorkspaceMemberPage
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
data | WorkspaceMember[] | 예 | 이 페이지의 항목입니다. 항목이 없으면 빈 배열입니다. |
pagination | Pagination | 예 | 결과가 더 있는지와 다음 페이지를 가져올 커서를 나타냅니다. |
WorkspaceMember
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
name | `string \ | null` | 예 |
role | string | 예 | 워크스페이스 접근 역할입니다. workspace_owner, workspace_admin, workspace_editor, workspace_viewer, external_collaborator 중 하나입니다. external_collaborator는 워크스페이스 멤버십이 아니라 특정 프로젝트에 대한 접근 권한을 가진 사용자를 나타냅니다. 값이 추가될 수 있으므로 클라이언트는 알 수 없는 값을 허용해야 합니다. |
user_id | string | 예 | 사용자를 식별하는 공개 UUID입니다(format: uuid). |
type | string | 예 | identity 타입입니다. 현재 값은 user입니다. 클라이언트는 알 수 없는 값을 허용해야 합니다. |
Pagination
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
has_more | boolean | 예 | 이 페이지 뒤에 결과가 더 있으면 true입니다. |
next_cursor | string 또는 null | 예 | 다음 페이지를 가져올 때 cursor 쿼리 매개변수로 전달할 값입니다. 불투명 문자열로 취급하세요. 결과가 더 없으면 null입니다. |
ErrorResponse
공통 오류 응답입니다.
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
detail | `string \ | null` | 예 |
errors | `array \ | null` | 예 |
props | `object \ | null` | 예 |
request_id | string | 예 | X-Request-Id 응답 헤더에서 반복되는 이 요청의 식별자입니다. |
status | integer | 예 | 본문에 반복되는 HTTP 상태 코드입니다. |
title | string | 예 | 사람이 읽을 수 있는 오류 요약입니다. |
type | string | 예 | 안정적인 machine-readable 오류 유형입니다. |
원본에 포함된 이 작업의 OpenAPI 스냅샷은 YAML 스냅샷 (SHA-256: ba9124b3aece607e3f9f6e2a57d317261f3d3ab343674ad112aec0af71133e9a)로 보존했습니다. 최신 전체 OpenAPI 계약은 https://api.lovable.dev/v1/openapi.yaml에서 확인할 수 있습니다.