> ## 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.

# GET/Token

> 프라이빗 모드에서 암호화된 토큰 조회 API 가이드

등록된 토큰을 안전하게 조회합니다. 단일 토큰 상세 조회 또는 전체 토큰 목록 조회가 가능합니다.

<Info>
  **안전한 데이터 전송** 옵션 활성화 시, 응답 데이터가 AES-256으로 암호화되어 전송됩니다.
</Info>

## 기본 정보

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

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

## 보안 설정

### 암호화 옵션

<Check>
  **안전한 데이터 전송** 활성화 시 모든 응답 데이터가 AES-256 암호화로 보호됩니다.
</Check>

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

### 인증

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

```bash theme={null}
x-api-key: {{YOUR_API_KEY}}
```

## 토큰 조회 유형

1. 단 건 조회

* 특정 tokenId 1개에 대한 상세 조회 (요청 당 1건)

2. 리스트 조회

* 전체 토큰 리스트 조회: 1회 요청당 10,000건
* 등록된 tokenId가 10,000건 초과 시, 페이지네이션 field ('nextPageKeyId', 'nextPageKeyTime') 제공

3. 총 갯수 조회

* 등록된 전체 토큰 갯수 조회 (요청 당 전체 N개)

## 요청 파라미터

### Query Parameters

<ParamField query="tokenId" type="String">
  특정 토큰 ID

  * **제공 시**: 단일 토큰 상세 조회
  * **미제공 시**: 전체 토큰 목록 조회
</ParamField>

<ParamField query="type" type="String">
  `count`

  * **제공 시**: 등록되어 있는 토큰의 총 갯수만 조회
  * **미제공 시**: 등록되어 있는 토큰들과 만료 유무 및 갯수 제공
</ParamField>

<RequestExample>
  ```bash 특정 토큰 조회 theme={null}
  GET /submission/tokens?tokenId=user001a
  ```

  ```bash 전체 토큰 목록 조회   theme={null}
  GET /submission/tokens
  ```

  ```bash 전체 토큰 갯수 조회 theme={null}
  GET /submission/tokens?type=count
  ```
</RequestExample>

## 응답

### 성공 응답 (200)

<Tabs>
  <Tab title="단일 토큰 조회">
    <ResponseField name="success" type="Boolean" required>
      조회 성공 여부
    </ResponseField>

    <ResponseField name="tokenId" type="String" required>
      조회된 토큰 ID
    </ResponseField>

    <ResponseField name="data" type="Object" required>
      토큰 데이터

      <Expandable title="data 속성">
        <ResponseField name="tokenId" type="String">
          토큰 ID
        </ResponseField>

        <ResponseField name="updateTime" type="String">
          최종 업데이트 시간 (ISO 8601 형식)
        </ResponseField>

        <ResponseField name="expired" type="Boolean">
          \[true, false]
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseExample>
      ```json 단일 토큰 조회 응답 theme={null}
      {
        "success": true,
        "tokenId": "user001a",
        "data": {
          "tokenId": "user001a",
          "updateTime": "2024-01-15T10:30:45.123Z"
        }
      }
      ```
    </ResponseExample>
  </Tab>

  <Tab title="전체 목록 조회">
    <ResponseField name="success" type="Boolean" required>
      조회 성공 여부
    </ResponseField>

    <ResponseField name="tokenId" type="Array<String>" required>
      토큰 ID 목록
    </ResponseField>

    <ResponseField name="data" type="Array<Object>" required>
      토큰 데이터 배열

      <Expandable title="data 배열 속성">
        <ResponseField name="tokenId" type="String">
          토큰 ID
        </ResponseField>

        <ResponseField name="updateTime" type="String">
          최종 업데이트 시간 (ISO 8601 형식)
        </ResponseField>

        <ResponseField name="expired" type="Boolean">
          \[true, false]
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="Number" required>
      총 토큰 수
    </ResponseField>

    <ResponseField name="nextgPageKey" type="Object" required>
      페이징 키 객체

      <Expandable title="nextgPageKey 배열 속성">
        <ResponseField name="id" type="String">
          페이징 키 Id
        </ResponseField>

        <ResponseField name="time" type="String">
          페이징 키 Time
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseExample>
      ```json 전체 목록 조회 응답 theme={null}
      {
        "success": true,
        "tokenId": ["user001a", "api.key.01", "token-123-abc"],
        "data": [
          {
            "tokenId": "user001a",
            "updateTime": "2024-01-15T10:30:45.123Z"
          },
          {
            "tokenId": "api.key.01",
            "updateTime": "2024-01-15T09:15:30.456Z"
          },
          {
            "tokenId": "token-123-abc",
            "updateTime": "2024-01-15T08:45:12.789Z"
          }
        ],
        "count": 3,
      	"nextPageKey" : {
      	  "id": "sample.id.01",
      	  "time": "2024-01-15T08:45:12.792Z"
      	}
      }
      ```
    </ResponseExample>
  </Tab>

  <Tab title="전체 갯수 조회">
    <ResponseField name="success" type="Boolean" required>
      조회 성공 여부
    </ResponseField>

    <ResponseField name="totalCount" type="Number" required>
      등록된 전체 토큰 갯수
    </ResponseField>

    <ResponseExample>
      ```json 전체 갯수 조회 theme={null}
      {
        "success": true,
        "totalCount": 4991
      }
      ```
    </ResponseExample>
  </Tab>
</Tabs>

<Tip>
  data\['expired'] 값을 통해, 기존에 제출한 것들 중, token이 만료된 건을 확인해서 DELETE-token에 활용할 수 있습니다.
</Tip>

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

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

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

<ResponseExample>
  ```json 토큰을 찾을 수 없음 theme={null}
  {
    "errorCode": "token_not_found",
    "errorMessage": "Token not found."
  }
  ```

  ```json 토큰 상세 정보 조회 실패 theme={null}
  {
    "errorCode": "token_id_details_not_found", 
    "errorMessage": "Token details could not be retrieved."
  }
  ```
</ResponseExample>

## 보안 고려사항

### 데이터 보호

<Warning>
  토큰 조회 시 민감한 정보가 포함될 수 있습니다. 프로덕션 환경에서는 보안을 위해서 암호화 옵션을 고려해 보세요.
</Warning>

* **암호화 전송**: AES-256을 통한 응답 데이터 암호화
* **접근 제어**: API 키를 통한 프로젝트별 접근 제한
* **사전 검증**: 옵션 활성화 여부와 관계없이 API 조회 가능

### 토큰 정책

<Info>
  **Token Pool**: 각 PID별 최대 100,000개 토큰 관리
  **조회 범위**: 프로젝트 범위 내 토큰만 조회 가능
</Info>

## 에러 코드

### 공통 에러

| 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개) |

## 사용 예시

<Steps>
  <Step title="전체 토큰 목록 확인">
    먼저 프로젝트에 등록된 모든 토큰을 조회합니다.

    ```bash theme={null}
    curl -X GET 'https://rest-api.argosidentity.com/v3/submission/tokens' \
      -H 'x-api-key: YOUR_API_KEY'
    ```

    <Check>
      응답에서 `count` 필드로 총 토큰 수를 확인할 수 있습니다.
    </Check>
  </Step>

  <Step title="특정 토큰 상세 조회">
    특정 토큰의 상세 정보를 조회합니다.

    ```bash theme={null}
    curl -X GET 'https://rest-api.argosidentity.com/v3/submission/tokens?tokenId=user001a' \
      -H 'x-api-key: YOUR_API_KEY'
    ```

    <Check>
      `updateTime`을 통해 토큰의 최종 업데이트 시간을 확인할 수 있습니다.
    </Check>
  </Step>
</Steps>

<Note>
  암호화된 환경에서는 응답 데이터 또한 암호화되어 제공됩니다.<br />
  해당 데이터에 대한 복호화 처리가 필요합니다.<br />
  암호화와 복호화 방법은, [데이터 암호화 및 복호화](/ko/idcheck/getting-started/encrypt-and-decrypt-data/overview)를 참고하세요.
</Note>