인증된 이메일 주소를 사용자의 기본 주소로 설정

POST /v1/users/{user_id}/emails/{email_id}:set-primary · 권한 users:write

인증된 주소를 사용자의 기본 주소로 설정합니다. 이전 기본 주소는 보조 주소로 유지됩니다. 인증되지 않은 주소는 기본 주소가 될 수 없습니다. 주소가 이미 기본 주소이면 아무것도 기록되지 않으며 200이 반환됩니다. 이 변경은 API 키를 행위자로 하여 관리 감사 로그에 user.primary_email_changed로 기록되고, user.updated 이벤트를 발생시킵니다.

요청

매개변수 위치 필수 설명
user_id path 예 사용자 ID이며 usr_ 접두사가 붙습니다.
email_id path 예 이메일 행의 ID(내부 UUID, 소문자, 하이픈 포함). GET /v1/users/{user_id}/emails가 반환한 값입니다.

이 요청은 본문을 받지 않습니다(빈 본문 또는 {}를 허용합니다).

응답

200 OK와 함께 업데이트된 이메일 행을 반환합니다. users:read_pii 권한이 없으면 주소가 마스킹됩니다(a***@e***.com).

{
  "id": "0191f0a0-3333-7444-8555-666666666666",
  "email": "ada@example.com",
  "verified": true,
  "primary": true,
  "created_at": "2026-01-15T09:30:00Z"
}

오류

모든 오류는 안정적인 code가 포함된 application/problem+json 본문으로 반환됩니다.

HTTP code 발생 조건
400 malformed_request, unknown_field 본문이 유효한 JSON이 아니거나, 비어 있지도 않고 {}도 아닙니다.
409 primary_requires_verified 주소가 인증되지 않았습니다.
404 not_found 이 환경에 사용자 또는 이메일 행이 없거나, 이메일이 이 사용자에게 속하지 않거나, ID 형식이 잘못되었습니다.
401 unauthenticated API 키가 없거나 유효하지 않거나 폐기되었습니다.
403 insufficient_permissions 키에 users:write 권한이 없습니다.
429 rate_limited 요청 한도를 초과했습니다. Retry-After를 따르십시오.
503 service_unavailable 종속 서비스를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하십시오.

예제

curl -X POST https://api.eu.keenauth.com/v1/users/usr_0a1b2c3d4e5f6g7h8j9k0m1n2p/emails/0191f0a0-3333-7444-8555-666666666666:set-primary \
  -H "Authorization: Bearer $KEENAUTH_SECRET_KEY"

개인 정보

이 엔드포인트는 개인 정보를 다룹니다. 최종 사용자 프로필이 포함됩니다. KeenAuth API의 개인 정보에서 저장되는 항목, 보관 기간, 삭제 방법을 확인할 수 있습니다. 어떤 필드에도 특수 범주의 개인 정보(건강, 생체 정보, 종교, 정치적 견해, 성적 지향)를 보내지 마십시오.