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

> Encrypted token retrieval API guide in private mode

Securely retrieve registered tokens. You can perform detailed retrieval of a single token or retrieval of the entire token list.

<Info>
  When the **Secure Data Transmission** option is enabled, response data is transmitted encrypted with AES-256.
</Info>

## Basic Information

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

## Security Settings

### Encrypted Transmission

<Check>
  When **Secure Data Transmission** is enabled, all response data is protected with AES-256 encryption.
</Check>

* Encryption method: **AES-256**
* Coverage: Response data
* Compatibility: Same encryption/decryption method as POST/submission, PATCH/submission, DELETE/submission, Webhook
* [Secure Data Transfer Options](/en/idcheck/getting-started/encrypt-and-decrypt-data/overview#4-secure-data-transfer-options)

### Authentication

<ParamField header="x-api-key" type="string" required>
  Set your project API key.
</ParamField>

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

## Token Retrieval Types

1. Single retrieval

* Detailed retrieval of specific tokenId (1 per request)

2. List retrieval

* Entire token list retrieval: 10,000 per request
* When registered tokenId exceeds 10,000, pagination fields ('nextPageKeyId', 'nextPageKeyTime') are provided

3. Total count retrieval

* Retrieve total count of registered tokens (entire N count per request)

## Request Parameters

### Query Parameters

<ParamField query="tokenId" type="String">
  Specific token ID

  * **When provided**: Single token detailed retrieval
  * **When not provided**: Entire token list retrieval
</ParamField>

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

  * **When provided**: Retrieve only the total count of registered tokens
  * **When not provided**: Provide registered tokens and expiration status and count
</ParamField>

<RequestExample>
  ```bash Specific token retrieval theme={null}
  GET /submission/tokens?tokenId=user001a
  ```

  ```bash Entire token list retrieval   theme={null}
  GET /submission/tokens
  ```

  ```bash Total token count retrieval theme={null}
  GET /submission/tokens?type=count
  ```
</RequestExample>

## Response

### Success Response (200)

<Tabs>
  <Tab title="Single token retrieval">
    <ResponseField name="success" type="Boolean" required>
      Retrieval success status
    </ResponseField>

    <ResponseField name="tokenId" type="String" required>
      Retrieved token ID
    </ResponseField>

    <ResponseField name="data" type="Object" required>
      Token data

      <Expandable title="data properties">
        <ResponseField name="tokenId" type="String">
          Token ID
        </ResponseField>

        <ResponseField name="updateTime" type="String">
          Last update time (ISO 8601 format)
        </ResponseField>

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

    <ResponseExample>
      ```json Single token retrieval response theme={null}
      {
        "success": true,
        "tokenId": "user001a",
        "data": {
          "tokenId": "user001a",
          "updateTime": "2024-01-15T10:30:45.123Z"
        }
      }
      ```
    </ResponseExample>
  </Tab>

  <Tab title="Entire list retrieval">
    <ResponseField name="success" type="Boolean" required>
      Retrieval success status
    </ResponseField>

    <ResponseField name="tokenId" type="Array<String>" required>
      Token ID list
    </ResponseField>

    <ResponseField name="data" type="Array<Object>" required>
      Token data array

      <Expandable title="data array properties">
        <ResponseField name="tokenId" type="String">
          Token ID
        </ResponseField>

        <ResponseField name="updateTime" type="String">
          Last update time (ISO 8601 format)
        </ResponseField>

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

    <ResponseField name="count" type="Number" required>
      Total token count
    </ResponseField>

    <ResponseField name="nextPageKey" type="Object" required>
      Pagination key object

      <Expandable title="nextPageKey array properties">
        <ResponseField name="id" type="String">
          Pagination key Id
        </ResponseField>

        <ResponseField name="time" type="String">
          Pagination key Time
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseExample>
      ```json Entire list retrieval response 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="Total count retrieval">
    <ResponseField name="success" type="Boolean" required>
      Retrieval success status
    </ResponseField>

    <ResponseField name="totalCount" type="Number" required>
      Total count of registered tokens
    </ResponseField>

    <ResponseExample>
      ```json Total count retrieval theme={null}
      {
        "success": true,
        "totalCount": 4991
      }
      ```
    </ResponseExample>
  </Tab>
</Tabs>

<Tip>
  You can use the data\['expired'] value to check which tokens have expired among previously submitted ones and utilize it for DELETE-token operations.
</Tip>

### Error Response (400/500)

<ResponseField name="errorCode" type="String" required>
  Error code
</ResponseField>

<ResponseField name="errorMessage" type="String" required>
  Error message
</ResponseField>

<ResponseExample>
  ```json Token not found theme={null}
  {
    "errorCode": "token_not_found",
    "errorMessage": "Token not found."
  }
  ```

  ```json Token details retrieval failed theme={null}
  {
    "errorCode": "token_id_details_not_found", 
    "errorMessage": "Token details could not be retrieved."
  }
  ```
</ResponseExample>

## Security Considerations

### Data Protection

<Warning>
  Token retrieval may contain sensitive information. Consider enabling the encryption option for security in production environments.
</Warning>

* **Encrypted transmission**: Response data encryption through AES-256
* **Access control**: Project-level access restriction through API keys
* **Pre-validation**: API retrieval possible regardless of option activation status

### Token Policy

<Info>
  **Token Pool**: Manage up to 100,000 tokens per PID
  **Retrieval scope**: Can only retrieve tokens within project scope
</Info>

## Error Codes

### Common Errors

| Error Code                 | HTTP Status | Description                              |
| -------------------------- | ----------- | ---------------------------------------- |
| invalid\_payload           | 400         | Missing request payload or format error  |
| invalid\_path              | 400         | Unsupported HTTP method                  |
| invalid\_project           | 400         | Missing project ID or invalid API key    |
| invalid\_query\_parameters | 400         | Missing query parameters or format error |
| invalid\_order             | 400         | Query parameter order format error       |
| internal\_server\_error    | 500         | Internal server error                    |

### Token Related Errors

| Error Code                      | HTTP Status | Description                                            |
| ------------------------------- | ----------- | ------------------------------------------------------ |
| invalid\_token\_id              | 400         | Missing token ID, empty value, or not an array         |
| invalid\_token\_id\_format      | 400         | Token ID format rule violation                         |
| invalid\_token\_id\_type        | 400         | Token ID is not a string                               |
| invalid\_token\_id\_length      | 400         | Token ID length outside 8-64 character range           |
| invalid\_token\_id\_whitespace  | 400         | Token ID contains whitespace characters                |
| invalid\_token\_id\_characters  | 400         | Token ID contains disallowed characters                |
| invalid\_token\_id\_start       | 400         | Token ID does not start with letter/number             |
| invalid\_token\_id\_end         | 400         | Token ID does not end with letter/number               |
| request\_token\_limit\_exceeded | 400         | Request token count limit exceeded (500)               |
| token\_limit\_exceeded          | 400         | Project token total count limit exceeded (100,000)     |
| token\_id\_not\_found           | 400         | Requested token does not exist in pool                 |
| token\_id\_details\_not\_found  | 400         | Token details retrieval failed                         |
| delete\_token\_limit\_exceeded  | 400         | Time-based bulk deletion request count exceeded (5000) |

## Usage Examples

<Steps>
  <Step title="Check entire token list">
    First, retrieve all tokens registered in the project.

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

    <Check>
      You can check the total token count through the `count` field in the response.
    </Check>
  </Step>

  <Step title="Retrieve specific token details">
    Retrieve detailed information for a specific token.

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

    <Check>
      You can check the token's last update time through `updateTime`.
    </Check>
  </Step>
</Steps>

<Note>
  In encrypted environments, response data is also provided encrypted.<br />
  Decryption processing is required for this data.<br />
  For encryption and decryption methods, refer to [Data Encryption and Decryption](/en/idcheck/getting-started/encrypt-and-decrypt-data/overview).
</Note>