구성원 초대
POST /fapi/v1/organizations/{org_id}/invitations · 환경의 로그인 호스트에서 호출
이메일 주소를 조직에 초대합니다. 초대 이메일은 KeenAuth가 발송하며, 초대 토큰과 수락 링크는 응답으로 반환되지 않습니다. 같은 주소와 같은 역할로 대기 중인 초대가 이미 있으면 다시 발송되며 응답은 200 OK입니다. 새 초대는 201 Created를 반환합니다.
정확한 Origin이 포함된 인증된 사용자의 __Host-idp_session 쿠키 또는 자사 앱의 프런트 API 액세스 토큰(DPoP 증명과 함께 Authorization: DPoP <token>)이 필요합니다. 자세한 내용은 프런트 API 액세스 토큰을 참조하십시오. 사용자는 idp_members:invite 권한을 가진 조직의 활성 구성원이어야 합니다. 구성원이 아닌 사용자에게는 404 not_found를 반환하며, 권한이 없는 구성원에게는 403 insufficient_permissions를 반환합니다. 특권 역할로 초대하려면 관리자 역할을 가진 구성원이어야 합니다(403 role_not_assignable).
@keenauth/js를 사용하는 경우: const { invitation, resent } = await keenauth.organizations.invite(orgId, { email, roleIds: [roleId] }).
요청
헤더:
| 헤더 | 필수 | 설명 |
|---|---|---|
Idp-Client |
예 | SDK 식별자입니다. |
Origin |
쿠키 사용 시 예 | https://<sign-in host>입니다. |
org_id: 조직 식별자(org_…)입니다.
본문:
| 필드 | 필수 | 설명 |
|---|---|---|
email |
예 | 초대할 이메일 주소입니다. 최대 254자입니다. |
role_ids |
아니요 | 최대 10개의 역할(rol_…)입니다. 지정하지 않으면 조직의 기본 역할이 적용됩니다. |
ttl_days |
아니요 | 초대의 유효 기간이며 1~30일입니다. 생략하면 환경의 기본값이 적용됩니다. |
응답
Location과 ETag를 포함한 201 Created, 또는 대기 중인 초대를 다시 발송한 경우 200 OK를 반환합니다. 본문은 초대 정보입니다.
id(inv_…), email(대기 중일 때만 표시되며, 그 외에는 null), role_ids, delivery, delivery_status(queued, sent, bounced 또는 not_sent), status(pending, accepted, revoked 또는 expired), send_count, last_sent_at, expires_at, accepted_user_id, accepted_at, revoked_at, created_at, updated_at, version.
오류
| 상태 | 코드 | 발생 조건 |
|---|---|---|
| 400 | unknown_field |
위에 나열되지 않은 필드가 본문에 있습니다. |
| 401 | unauthenticated |
유효한 세션 쿠키나 토큰이 없습니다. |
| 403 | insufficient_permissions |
사용자에게 해당 조직의 idp_members:invite 권한이 없습니다. |
| 403 | role_not_assignable |
역할이 특권 역할이고, 사용자가 관리자 역할을 가지고 있지 않습니다. |
| 403 | origin_not_allowed |
Origin이 일치하지 않습니다. |
| 404 | not_found |
이 사용자에 대한 조직 또는 역할이 없습니다. |
| 409 | invitation_already_pending |
같은 주소에 대해 다른 역할의 대기 중인 초대가 있습니다. |
| 409 | membership_already_exists |
해당 주소는 조직의 구성원에 속해 있습니다. |
| 409 | organization_membership_limit_reached |
조직이 구성원 수 제한에 도달했습니다. |
| 409 | organization_disabled |
조직이 비활성화되었거나 삭제 대기 중입니다(organization_pending_deletion). |
| 422 | validation_failed |
email, role_ids 또는 ttl_days가 없거나 잘못되었습니다. |
| 429 | invite_rate_limited |
초대 또는 재발송 횟수가 너무 많습니다. Retry-After초 후에 다시 시도하십시오. |
| 501 | not_implemented |
이 환경에서는 초대 이메일이 설정되어 있지 않습니다. |
| 503 | service_unavailable |
일시적으로 사용할 수 없습니다. Retry-After초 후에 다시 시도하십시오. |
예시
curl -X POST "https://example.keenauth.app/fapi/v1/organizations/org_01jbz6x8kq3m2n4p5r6s7t8v9a/invitations" \
-H "Idp-Client: my-app/1.0.0 (node/22.0.0)" \
-H "Origin: https://example.keenauth.app" \
-H "Content-Type: application/json" \
-b cookies.txt \
-d '{"email":"new.member@example.com","role_ids":["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"],"ttl_days":7}'
{
"id": "inv_01jbz6x8kq3m2n4p5r6s7t8v9d",
"email": "new.member@example.com",
"role_ids": ["rol_01jbz6x8kq3m2n4p5r6s7t8v9w"],
"delivery": "email",
"delivery_status": "queued",
"status": "pending",
"send_count": 1,
"last_sent_at": "2026-11-03T10:00:00Z",
"expires_at": "2026-11-10T10:00:00Z",
"accepted_user_id": null,
"accepted_at": null,
"revoked_at": null,
"created_at": "2026-11-03T10:00:00Z",
"updated_at": "2026-11-03T10:00:00Z",
"version": 1
}
개인정보
이 엔드포인트는 개인정보, 즉 조직 구성원 정보와 초대 정보를 다룹니다. KeenAuth API의 개인정보에서 저장되는 항목, 보관 기간, 삭제 방식을 설명합니다. 어떤 필드에도 특수 범주의 개인정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.