추가¶
POST /api/v1/account/add
개요¶
로컬 계정을 생성하거나 서드파티 exterId로 연동 계정을 생성합니다.
호출 전 및 사용 단계¶
w 권한의 External 자격 증명이 필요합니다. 로컬 계정은 exterId를 생략하고, 서드파티 SSO 계정은 안정적인 exterId를 제공하며 password=""를 명시합니다. source는 이 인터페이스의 공개 입력 파라미터가 아니며, 로컬은 local로 고정되고 서드파티는 기본적으로 unknown입니다. 성공 후 content.uuid를 저장합니다. 계정 생성 시 워크스페이스에 자동으로 추가되지 않으며, 워크스페이스 연결은 해당 멤버 관리 기능을 사용하세요. 타임아웃 또는 500 발생 시 먼저 계정 목록 또는 계정 상세로 생성 여부를 확인한 후 재시도하세요. 생성 시 내부적으로 계정을 먼저 제출하므로 멱등 키를 지원하지 않습니다.
요청 헤더¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| X-Df-SVersion | string | 원본 경로 및 요청 본문 서명 버전이며, 생략한 후 이 페이지의 알고리즘을 계속 사용할 수 없습니다. 예시: v20240417획득 또는 입력 방법: 이 페이지의 예시는 이 고정 버전을 사용하며, 예시 서명 알고리즘과 함께 사용됩니다. |
|
| X-Df-Access-Key | string | Y | 읽기 인터페이스는 r 또는 w 자격 증명을 사용할 수 있고, 쓰기 인터페이스는 w 자격 증명이 필요합니다. 예시: <external-access-key>획득 또는 입력 방법: 사이트 관리자가 할당한 External API AK를 사용하며, 워크스페이스 OpenAPI Key는 사용할 수 없습니다. |
| X-Df-Nonce | string | Y | 임시 일련번호이며, 실패 후 재전송 시에도 새 값을 생성하고 서명을 다시 계산합니다. 예시: 97d275ee9f774315a7885ba7347acbd9획득 또는 입력 방법: 요청마다 uuid.uuid4().hex를 새로 생성합니다. |
| X-Df-Signature | string | Y | 대문자 메서드, nonce, 원본 전체 경로, timestamp 및 원본 UTF-8 요청 본문을 공백으로 연결한 후 HMAC-SHA256을 수행하고 hex 다이제스트를 사용합니다. 예시: <hmac-sha256-hex>획득 또는 입력 방법: External API 서명 인증에 따라 함께 제공된 SK로 계산하며, 전체 실행 가능한 템플릿은 아래와 같습니다. |
| X-Df-Timestamp | string | Y | 사이트에 구성된 서명 유효 시간 범위 내에 있어야 하며, 예시 시간을 재사용할 수 없습니다. 예시: 1785427200획득 또는 입력 방법: 전송 시 str(int(time.time()))로 현재 Unix 초 문자열을 생성합니다. |
Body 요청 파라미터¶
| 파라미터명 | 타입 | 필수 | 설명 |
|---|---|---|---|
| attributes | json | 선택적 객체이며 생략 시 기본값은 {}입니다. 객체 전체가 저장되고, 값은 문자열 사용을 권장하며 이후 SSO 로그인 시 덮어쓸 수 있습니다. null일 수 없습니다. null 허용: False 예시: {"部门": "研发部"}획득 또는 입력 방법: SSO 매핑 규칙 또는 기업 신원 시스템에서 KV 객체를 가져오며, 필드명은 연동 양측이 약정합니다. |
|
| brandKey | string | 선택 사항이며, 생략 시 사이트 기본 브랜드를 사용합니다. null일 수 없으며, 모든 브랜드 사이트에서 이 값을 허용한다고 임의로 가정할 수 없습니다. null 허용: False 예시: guance획득 또는 입력 방법: 사이트 관리자에게 허용된 브랜드 식별자를 확인합니다. |
|
| countryCode | string | 문자열 국가/지역 코드입니다. 생략하고 mobile이 기존 11자리 국내 번호이면 86을 추론할 수 있으며, mobile이 비어 있으면 최종적으로 비어 있게 됩니다. 빈 문자열 허용: True null 허용: False 예시: 1획득 또는 입력 방법: 멤버 휴대전화 번호의 국가/지역에서 가져옵니다. 예: 중국 86, 미국 1. |
|
| customAttributes | json | 선택적 객체이며 생략 시 기본값은 {}입니다. 비즈니스 측에서 유지 관리하며, 값은 문자열 사용을 권장합니다. null일 수 없습니다. null 허용: False 예시: {"costCenter": "CC-1001"}획득 또는 입력 방법: 귀하의 비즈니스 계정 속성에서 KV 객체를 가져옵니다. 예: 비용 센터. |
|
| string | Y | 필수이며, 값이 있으면 이메일 형식을 검증합니다. 빈 문자열이고 username이 이메일 형식이면 자동으로 username으로 채워집니다. null일 수 없습니다. 빈 문자열 허용: True null 허용: False $isEmail: True 예시: xxx@guance.com획득 또는 입력 방법: 멤버가 알림을 수신할 수 있는 유효한 이메일을 사용하며, 이메일이 없으면 빈 문자열을 명시적으로 전달할 수 있습니다. |
|
| extend | json | 선택적 객체 또는 null이며, 현재 생성 구현은 이 필드를 저장하지 않지만 응답은 일반적으로 null입니다. null 허용: True 예시: {}획득 또는 입력 방법: 현재 선언과의 호환을 위한 것으로만 사용하며, 이 필드에 추가 정보를 저장하는 것에 의존하지 말고 비즈니스 사용자 정의 데이터는 customAttributes에 넣으세요. |
|
| exterId | string | 선택 사항입니다. 비어 있지 않은 값은 서드파티 생성 분기를 활성화하며 빈 네임스페이스 내에서 유일하고, 이때 source는 자동으로 unknown이 됩니다. 생략하면 local 로컬 계정을 생성합니다. 서드파티 신원을 표현하기 위해 null 또는 빈 값을 전달하지 마세요. 빈 문자열 허용: False null 허용: False 예시: sso-user-1001획득 또는 입력 방법: 귀하의 SSO/ID 제공자의 안정적인 사용자 ID에서 가져오며, 변경될 수 있는 닉네임은 사용할 수 없습니다. |
|
| isDisable | boolean | 이 선택적 불리언 필드는 현재 생성 상태를 변경하지 않으며 새 계정은 여전히 status=0입니다. isDisable=true로 비활성화된 계정을 생성하는 것에 의존하지 마세요. null 허용: False 선택 값: [True, False] 예시: false획득 또는 입력 방법: 새 계정을 비활성화하려면 생성 성공 후 uuid를 얻은 뒤 활성화/비활성화를 호출하세요. |
|
| language | string | 선택 사항이며, 생략, null 또는 빈 문자열은 모두 기본값 zh입니다. 값이 있으면 선언된 열거형 내에 있어야 합니다. 빈 문자열 허용: True null 허용: True 선택 값: ['zh', 'en', 'zh-hant', 'id', 'ja', 'ko'] 예시: zh획득 또는 입력 방법: 멤버 선호도에 따라 zh, en, zh-hant, id, ja, ko 중 하나를 선택합니다. |
|
| mobile | string | 휴대전화 필드는 countryCode와 로컬 mobile 두 부분으로 구성됩니다. + 국제 번호 또는 00 접두사 국제 번호를 지원하며, 1로 시작하는 11자리 기존 국내 번호는 기본적으로 86으로 처리될 수 있습니다. 지역 코드를 제공하면 전체 번호의 유효성을 검증합니다. 생략 시 기본값은 비어 있으며, null을 전달하지 마세요. 빈 문자열 허용: False null 허용: False 예시: 2025550123획득 또는 입력 방법: 멤버의 실제 유효한 휴대전화 로컬 번호를 countryCode와 함께 사용하며, 구성하지 않을 때는 생략합니다. |
|
| name | string | Y | 필수 닉네임이며, 의미 있는 비어 있지 않은 문자열을 제공합니다. 빈 문자열 허용: False null 허용: False 예시: 示例成员획득 또는 입력 방법: 신원 시스템의 멤버 표시 이름을 사용합니다. |
| password | string | Y | 필수입니다. exterId가 없으면 최소 8자이며 숫자/대문자/소문자/특수 문자 네 가지 중 최소 세 가지를 포함해야 합니다. exterId가 있으면 해당 강도 검증을 수행하지 않으며 빈 문자열일 수 있습니다. null을 전달하지 마세요: exterId가 없으면 400 ft.InvalidPasswordRule을 반환하고, exterId가 있으면 해시 생성으로 진입하여 500 ft.InternalServerError를 반환할 수 있습니다. 빈 문자열 허용: True null 허용: True 예시: Example!2026a획득 또는 입력 방법: 호출자가 로컬 계정용으로 생성하여 안전하게 전달하며, 서드파티 SSO 계정은 빈 문자열을 명시적으로 입력합니다. |
| username | string | Y | 필수입니다. exterId가 없으면 빈 네임스페이스 내에서 유일합니다. exterId가 있으면 중복이 허용되며 서드파티는 빈 문자열을 전달할 수 있습니다. null을 전달하지 마세요. 하위 데이터베이스가 null을 허용하지 않습니다. 빈 문자열 허용: True null 허용: True 예시: xxx@guance.com획득 또는 입력 방법: 로컬 계정은 사용되지 않은 로그인 이름을 사용하며 유효한 이메일을 권장합니다. 서드파티 계정은 귀하의 로그인 이름을 사용합니다. |
파라미터 추가 설명¶
사이트 수준 External API 자격 증명을 사용하며, 인증 방식은 External API 서명 인증을 참조하세요. 다음 예시는 v20240417 서명 버전을 사용하며, 서명 경로, Query 인코딩 및 원본 요청 본문은 실제 전송과 완전히 일치해야 합니다. 반환되는 계정 정보에는 password 필드가 포함되지 않으며, mfaSecret은 고정 마스크일 뿐 로그인에 사용할 수 있는 키가 아닙니다.
서드파티 계정 최소 요청 본문 예시:
로컬 비밀번호는 HTTPS 내의 원문 문자열을 사용하며, 이 인터페이스는 관리 콘솔의 RSA 비밀번호 래핑을 사용하지 않습니다.
표의 null/빈 문자열과 생략은 구분해야 합니다. 현재 문자열 타입 검증은 빈 문자열을 일괄적으로 차단하지 않으므로, 호출자는 로그인 이름, 닉네임 등에 의미 있는 비어 있지 않은 내용을 제공하고 빈 값으로 암시적 기본값을 얻는 것에 의존하지 않아야 합니다.
요청 예시¶
import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen
# 대상 사이트 주소 및 관리자가 할당한 External API AK/SK로 교체합니다.
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/account/add'
query = {}
data = {'username': 'xxx@guance.com', 'password': 'Example!2026a', 'name': '示例成员', 'email': 'xxx@guance.com', 'language': 'zh', 'attributes': {'部门': '研发部'}, 'customAttributes': {'costCenter': 'CC-1001'}}
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
"X-Df-Access-Key": access_key,
"X-Df-Timestamp": timestamp,
"X-Df-Nonce": nonce,
"X-Df-Signature": signature,
"X-Df-SVersion": "v20240417",
}
if data is not None:
headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
print(result.read().decode("utf-8"))
응답¶
HTTP 200, Content-Type은 application/json이며 통합 응답 셸입니다. 비즈니스 데이터는 content에 위치합니다. External API는 declaration에 자동으로 추가되지 않으며, 목록 페이징은 content.pageInfo에 유지됩니다.
| 필드 | 타입 | 설명 |
|---|---|---|
| content.id | integer | 사이트 내 계정 레코드 일련번호로, 정보 반환용으로만 사용됩니다. 다른 인터페이스 호출 시에는 uuid를 사용합니다. |
| content.uuid | string | 계정 UUID이며, 이후 조회, 수정, 비활성화, 삭제 시 이 필드를 사용합니다. |
| content.status | integer | 계정 상태: 0 정상, 2 비활성화. 목록 필터에서 3은 삭제됨이며, 기타 과거 상태가 나타날 수 있습니다. |
| content.creator | string | 생성 주체 식별자이며, External 생성은 일반적으로 SYS입니다. |
| content.updator | string | 최근 수정 주체 식별자이며, 아직 수정이 없으면 비어 있을 수 있습니다. |
| content.createAt | number | 생성 시간, Unix 초. |
| content.updateAt | number | 업데이트 시간, Unix 초이며, 아직 업데이트 시간이 없으면 -1일 수 있습니다. |
| content.deleteAt | number | 상태 작업 시간 필드로 초기에는 일반적으로 -1입니다. 활성화/비활성화 시에도 이 값이 기록되므로 단독으로 삭제 여부를 판단하지 말고 status를 사용해야 합니다. |
| content.name | string | 표시 닉네임. |
| content.username | string | 로그인 계정 이름. 서드파티 계정은 비어 있거나 다른 계정과 중복될 수 있습니다. |
| content.email | string | 계정 연락 이메일이며, 생성 시 비어 있고 username이 이메일 형식이면 username으로 채워집니다. |
| content.mobile | string | 휴대전화 로컬 번호로 복호화되어 표시되며 국가 지역 코드는 포함하지 않습니다. 미설정 시 빈 문자열입니다. |
| content.countryCode | string | 휴대전화 국가/지역 코드의 순수 숫자 문자열입니다. 예: 86. 미설정 시 빈 문자열입니다. |
| content.exterId | string | 서드파티 신원 시스템의 고유 ID이며, 로컬 계정은 일반적으로 비어 있습니다. |
| content.extend | object 또는 null | 기존 확장 정보로 user_icon 아바타 주소를 포함할 수 있습니다. 이 인터페이스 생성 시 전달한 extend는 현재 저장되지 않으며, 수정 인터페이스도 이 입력 파라미터를 공개하지 않습니다. |
| content.extend.user_icon | string | 선택적 아바타 URL 또는 정적 리소스 파일명입니다. 기존 정보를 읽을 때 나타날 수 있으며, 이 페이지에서 쓸 수 있는 파라미터는 아닙니다. |
| content.source | string | 신원 출처 식별자로, 예: local, unknown, oidc, ldap. agent 등 과거 내부 출처도 존재할 수 있습니다. |
| content.nameSpace | string | 신원 네임스페이스로, External 생성 시 기본값은 비어 있습니다. 이 모듈의 공개 파라미터로는 설정할 수 없습니다. |
| content.isUsed | integer 또는 boolean | 계정 사용 여부 표시. |
| content.agreeTerms | integer | 약관 동의 표시. |
| content.canaryPublic | boolean | 카나리 표시. |
| content.enableMFA | boolean | MFA 사용 여부. |
| content.mfaSecret | string | 고정 마스크 ********************* 이며, 사용 가능한 MFA 키를 포함하지 않습니다. |
| content.language | string | 언어 식별자. zh, en, zh-hant, id, ja, ko. |
| content.tokenHoldTime | integer | 계정 무작업 세션 유지 시간(초). 새 계정은 사이트 보안 세션 설정에 따라 초기화되며, 예시 값으로 고정된다고 보장할 수 없습니다. |
| content.tokenMaxValidDuration | integer | 계정 세션 최대 유효 기간(초). 새 계정은 사이트 보안 세션 설정에 따라 초기화됩니다. |
| content.timezone | string | 시간대 식별자, 미설정 시 비어 있습니다. |
| content.attributes | object | SSO 동기화 속성 KV 객체로, 이후 SSO 로그인 시 덮어쓸 수 있습니다. 키와 값은 연동 측이 약정합니다. |
| content.attributes.{属性名} | 임의 JSON 값 | 사용자 정의 속성 값으로, 문자열 사용을 권장합니다. 예: 部门=研发部. |
| content.customAttributes | object | 비즈니스 측에서 유지 관리하는 속성 KV 객체. |
| content.customAttributes.{属性名} | 임의 JSON 값 | 비즈니스 사용자 정의 값으로, 문자열 사용을 권장합니다. 예: costCenter=CC-1001. |
| content.statusPageSubs | integer | 상태 페이지 구독 표시. |
| content.defaultWorkspace | string | 계정 기본 워크스페이스 UUID, 미설정 시 비어 있습니다. |
| content.brandKey | string | 계정의 현재 브랜드 식별자로, 사이트에서 허용된 브랜드 집합에 따라 결정됩니다. |
| content.scheduleMobile | string | 스케줄 전용 휴대전화 로컬 번호, 미설정 시 비어 있습니다. |
| content.scheduleEmail | string | 스케줄 전용 이메일, 미설정 시 비어 있습니다. |
| content.ifScheduleMobileEnable | boolean | 스케줄 휴대전화 사용 여부. |
| content.ifScheduleEmailEnable | boolean | 스케줄 이메일 사용 여부. |
| content.accountStatus | string | 계정 부가 상태 식별자, 미설정 시 비어 있습니다. |
{
"code": 200,
"content": {
"id": 1001,
"uuid": "acnt_example001",
"status": 0,
"creator": "SYS",
"updator": "",
"createAt": 1785427200,
"deleteAt": -1,
"updateAt": -1,
"name": "示例成员",
"username": "xxx@guance.com",
"email": "xxx@guance.com",
"mobile": "",
"countryCode": "",
"exterId": "",
"extend": null,
"source": "local",
"nameSpace": "",
"isUsed": 0,
"agreeTerms": 0,
"canaryPublic": false,
"enableMFA": false,
"mfaSecret": "*********************",
"language": "zh",
"tokenHoldTime": 86400,
"tokenMaxValidDuration": 604800,
"timezone": "",
"attributes": {
"部门": "研发部"
},
"customAttributes": {
"costCenter": "CC-1001"
},
"statusPageSubs": 0,
"defaultWorkspace": "",
"brandKey": "guance",
"scheduleMobile": "",
"scheduleEmail": "",
"ifScheduleMobileEnable": false,
"ifScheduleEmailEnable": false,
"accountStatus": ""
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 레이트 리밋 및 공통 요청 오류는 공통 오류 정의를 참조하세요.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드 누락 또는 필드 값이 선언된 검증 조건 위반 | 파라미터 파싱 실패 | 파라미터 위치, 필드명, 타입 및 값을 확인합니다. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정합니다. |
| 400 | ft.JsonFormatError | 요청 본문 JSON 최상위가 객체가 아님 | 일부 json 파일 형식 오류 | JSON 객체를 사용하고 배열, 문자열 또는 null을 최상위로 전송하지 마세요. |
| 400 | ft.InvalidPasswordRule | 로컬 생성 시 비밀번호가 null, 빈 문자열 또는 강도 규칙 미충족. 수정 시 제공된 비어 있지 않은 비밀번호가 강도 규칙 미충족 | 유효하지 않은 비밀번호 규칙 | 비밀번호는 최소 8자이며 숫자, 대문자, 소문자, 특수 문자 네 가지 중 최소 세 가지를 포함해야 합니다. |
| 406 | ft.InvalidBrandKey | brandKey가 대상 사이트의 허용 집합에 없음 | 브랜드 식별자{}가 유효하지 않습니다. |
사이트 관리자에게 해당 사이트에서 허용되는 브랜드 식별자를 확인한 후 원래 값을 입력하세요. |
| 400 | ft.ObjectParmeterExists | 로컬 username 또는 서드파티 exterId가 삭제되지 않은 계정으로 이미 존재 | <username 또는 exterId> 가 이미 존재합니다 |
먼저 기존 계정을 조회하고, 업데이트는 수정 인터페이스를 사용하세요. 중복 생성을 멱등 성공으로 간주해서는 안 됩니다. |
| 429 | ft.OperationTooFrequently | 동일 username의 로컬 생성 잠금이 아직 해제되지 않음 | 작업이 너무 빈번합니다. 잠시 후 다시 시도하세요 | 잠시 기다린 후 먼저 기존 계정을 조회하고, 생성되지 않았음을 확인한 후 서명 요청을 다시 생성하세요. |
| 500 | ft.InternalServerError | 데이터베이스, 캐시, 비동기 작업 전달 또는 명시적으로 처리되지 않은 필드 예외 | 내부 오류 | traceId를 저장하고 관리자에게 문의하세요. 쓰기 요청은 먼저 계정 현재 상태를 다시 조회하고 확인한 후 재시도 여부를 결정해야 하며, 500을 곧바로 미적용으로 간주해서는 안 됩니다. |