> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST/Token

> 프라이빗 모드 및 암호화 설정을 통한 안전한 토큰 등록 API 가이드

토큰을 안전하게 등록합니다. 최대 100,000개까지 등록 가능하며, 요청 당 최대 500개까지 처리할 수 있습니다.

<Info>
  프라이빗 모드 및 암호화 설정 보안 기능을 통해 데이터를 안전하게 전송할 수 있습니다.
</Info>

## 기본 정보

<ParamField path="method" type="string" required>
  **POST**
</ParamField>

<ParamField path="url" type="string" required>
  [https://rest-api.argosidentity.com/v3/submission/tokens](https://rest-api.argosidentity.com/v3/submission/tokens)
</ParamField>

## 보안 설정

### 암호화 옵션

<Warning>
  **안전한 데이터 전송** 옵션을 활성화하면 요청 및 응답이 AES-256으로 암호화됩니다.
</Warning>

* 암호화 방식: **AES-256**
* 적용 범위: 요청 및 응답 데이터
* 호환성: POST/submission, PATCH/submission, GET/submission과 동일한 암/복호화 방식
* [안전한 데이터 전송 옵션](/ko/idcheck/getting-started/encrypt-and-decrypt-data/overview#4-안전한-데이터-전송-옵션) 확인하기

### 인증

<ParamField header="x-api-key" type="string" required>
  프로젝트 API 키를 설정합니다.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  요청 본문의 MIME 타입을 설정합니다.
</ParamField>

<Warning>
  POST 요청 시 `Content-Type: application/json`사용 시 요청이 실패할 경우 `text/plain`를 사용하세요.
</Warning>

```bash theme={null}
x-api-key: {{YOUR_API_KEY}}
Content-Type: text/plain
```

## 요청 파라미터

### Request Body

<ParamField body="tokenId" type="Array<String>" required>
  추가할 토큰 ID 배열 (1회 요청 시 최대 500개)

  **토큰 ID 형식 제약사항:**

  * **길이**: 8 Byte \~ 64 Byte
  * **허용 문자**: 영문자(a-z, A-Z), 숫자(0-9), 하이픈(-), 언더스코어(\_), 마침표(.)
  * **제한**: 공백, 탭, 개행문자 불가
  * **시작/끝**: 영문자 및 숫자만 가능
</ParamField>

<RequestExample>
  ```bash cURL 요청 예시 theme={null}
  curl -X POST 'https://rest-api.argosidentity.com/v3/submission/tokens' \
    -H 'x-api-key: YOUR_API_KEY' \
    -H 'Content-Type: text/plain' \
    -d '{
    "tokenId": [
      "user001a",
      "api.key.01", 
      "token-123-abc",
      "session_data_01"
    ]
  }'
  ```

  ```json 요청 Body (JSON 형식이지만 text/plain으로 전송) theme={null}
  {
    "tokenId": [
      "user001a",
      "api.key.01", 
      "token-123-abc",
      "session_data_01"
    ]
  }
  ```
</RequestExample>

## 응답

### 성공 응답 (200)

<ResponseField name="success" type="Boolean">
  작업 성공 여부
</ResponseField>

<ResponseField name="message" type="String">
  작업 결과 메시지
</ResponseField>

<ResponseField name="summary" type="Object">
  요약 정보

  <Expandable title="summary 속성">
    <ResponseField name="totalSubmitted" type="Number">
      제출된 총 토큰 수
    </ResponseField>

    <ResponseField name="currentCount" type="Number">
      등록 되어있는 총 토큰 수
    </ResponseField>

    <ResponseField name="processed" type="Number">
      성공적으로 처리된 토큰 수
    </ResponseField>

    <ResponseField name="failed" type="Number">
      실패한 토큰 수
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="details" type="Object">
  상세 정보 (실패 시에만 포함)

  <Expandable title="details 속성">
    <ResponseField name="failed" type="Array">
      실패한 토큰 목록

      <Expandable title="failed 배열 속성">
        <ResponseField name="tokenId" type="String">
          실패한 토큰 ID
        </ResponseField>

        <ResponseField name="error" type="String">
          실패 코드
        </ResponseField>

        <ResponseField name="message" type="String">
          실패 메시지
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 전체 성공 theme={null}
  {
    "success": true,
    "message": "All tokens are now in the pool",
    "summary": {
      "totalSubmitted": 4,
      "currentCount" : 3504,
      "processed": 4,
      "failed": 0
    }
  }
  ```

  ```json 부분 실패 theme={null}
  {
    "success": false,
    "message": "Some tokens failed to process",
    "summary": {
      "totalSubmitted": 4,
      "currentCount" : 3504,
      "processed": 3,
      "failed": 1
    },
    "details": {
      "failed": [
        {
          "tokenId": "token-123-abc",
          "error": "Process_failed",
          "message": "Write operation failed"
        }
      ]
    }
  }
  ```
</ResponseExample>

### 오류 응답 (400/500)

<ResponseField name="errorCode" type="String" required>
  에러 코드
</ResponseField>

<ResponseField name="errorMessage" type="String" required>
  에러 메시지
</ResponseField>

<ResponseField name="errorDetails" type="Object">
  에러 상세 정보 (선택적)
</ResponseField>

<ResponseExample>
  ```json 토큰 형식 오류 theme={null}
  {
    "errorCode": "invalid_token_id_format",
    "errorMessage": "One or more token IDs do not meet the required format specifications.",
    "errorDetails": {
      "invalidTokens": [
        {
          "tokenId": "short01",
          "errorCode": "invalid_token_id_length",
          "errorMessage": "Token ID length must be between 8 and 64 characters. Please adjust the token length."
        }
      ]
    }
  }
  ```
</ResponseExample>

## 토큰 정책

### 제한 사항

<Warning>
  **Token Pool**: 각 PID 별 최대 100,000개 (초과 시 에러 발생)
  **1회 요청**: 최대 500개 토큰 ID
</Warning>

<Warning>
  **중요**: 토큰 풀이 100,000개를 초과하면 에러가 발생합니다. 토큰 수 관리를 위해서 다음의 두가지 방법을 활용할 수 있습니다.

  * [DELETE 토큰 삭제 API](/api-reference/api-reference-guide/ko/delete-token)를 사용하여 불필요한 토큰을 미리 정리.
  * 대시보드 프라이빗 모드 설정에서 'Token Id 삭제 조건 설정'에서 토큰 만료 시 삭제 옵션 활성화; 사용된 토큰은 자동적으로 삭제됩니다.
</Warning>

### Partial Handling

<Info>
  POST 요청은 토큰 ID에 대해 부분적으로 처리됩니다.
  이미 Pool에 존재하는 토큰 ID는 덮어쓰기되며, 별도 중복 에러는 반환되지 않습니다.
</Info>

**예시:**

* Pool에 존재하는 Token ID: `tokenA`, `tokenB`, `tokenC`
* POST 요청: `tokenA`, `tokenC`, `tokenD`
* 요청 완료 후 Pool: `tokenA`, `tokenB`, `tokenC`, `tokenD`

## 에러 코드

### 공통 에러

| Error Code                 | HTTP Status | Description              |
| -------------------------- | ----------- | ------------------------ |
| invalid\_payload           | 400         | 요청 페이로드 누락 또는 형식 오류      |
| invalid\_path              | 400         | 지원하지 않는 HTTP 메서드         |
| invalid\_project           | 400         | 프로젝트 ID 누락 또는 잘못된 API 키  |
| invalid\_query\_parameters | 400         | 쿼리 파라미터 누락 또는 형식 오류      |
| invalid\_order             | 400         | 쿼리 파라미터의 정렬(order) 형식 오류 |
| internal\_server\_error    | 500         | 서버 내부 오류                 |

### Token 관련 에러

| Error Code                      | HTTP Status | Description                            |
| ------------------------------- | ----------- | -------------------------------------- |
| invalid\_token\_id              | 400         | 토큰 ID 누락, 빈 값, 또는 배열이 아님               |
| invalid\_token\_id\_format      | 400         | 토큰 ID 형식 규칙 위반                         |
| invalid\_token\_id\_type        | 400         | 토큰 ID가 문자열이 아님                         |
| invalid\_token\_id\_length      | 400         | 토큰 ID 길이가 8-64자 범위를 벗어남                |
| invalid\_token\_id\_whitespace  | 400         | 토큰 ID에 공백 문자 포함                        |
| invalid\_token\_id\_characters  | 400         | 토큰 ID에 허용되지 않는 문자 포함                   |
| invalid\_token\_id\_start       | 400         | 토큰 ID가 영문자/숫자로 시작하지 않음                 |
| invalid\_token\_id\_end         | 400         | 토큰 ID가 영문자/숫자로 끝나지 않음                  |
| request\_token\_limit\_exceeded | 400         | 요청 당 토큰 개수 제한 초과 (500개)                |
| token\_limit\_exceeded          | 400         | 프로젝트 당 토큰 총 개수 제한 초과 (100,000개)        |
| token\_id\_not\_found           | 400         | 요청한 토큰이 풀에 존재하지 않음                     |
| token\_id\_details\_not\_found  | 400         | 토큰 상세 정보 조회 실패                         |
| delete\_token\_limit\_exceeded  | 400         | 시간 순 다건 삭제 요청의 최대 갯수(count) 초과 (5000개) |

<Tip>
  암호화 설정을 통해 민감한 토큰 데이터를 안전하게 전송할 수 있습니다. 프로덕션 환경에서는 보안을 위해서 암호화 옵션을 활성화하여 고려할 수 있습니다.
</Tip>

<Tip>
  \*\*Liveform에서 QueryStirng에 사용법: [https://form.argosidentity.com?pid=\{projectid}\&token=\{POST로\_요청한\_tokenid}](https://form.argosidentity.com?pid=\{projectid}\&token=\{POST로_요청한_tokenid})
</Tip>

<Note>
  **Content-Type 주의사항**: POST 요청 시 `Content-Type: application/json`을 사용했을 때 오류가 나는 경우 `text/plain`으로 헤더를 설정하세요.
</Note>