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

> Secure token registration API guide with private mode and encryption settings

Securely register tokens. You can register up to 100,000 tokens per project, with a maximum of 500 tokens per request.

<Info>
  You can transmit data securely through private mode and encryption security features.
</Info>

## Basic Information

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

## Security Settings

### Encryption Option

<Warning>
  When the **Secure Data Transmission** option is enabled, requests and responses are encrypted with AES-256.
</Warning>

* Encryption method: **AES-256**
* Coverage: Request and response data
* Compatibility: Same encryption/decryption method as POST/submission, PATCH/submission, GET/submission
* [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>

<ParamField header="Content-Type" type="string" required>
  Set the MIME type of the request body.
</ParamField>

<Warning>
  When using `Content-Type: application/json` for POST requests, if the request fails, use `text/plain` instead.
</Warning>

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

## Request Parameters

### Request Body

<ParamField body="tokenId" type="Array<String>" required>
  Array of token IDs to add (maximum 500 per request)

  **Token ID format constraints:**

  * **Length**: 8 Byte \~ 64 Byte
  * **Allowed characters**: Letters (a-z, A-Z), numbers (0-9), hyphens (-), underscores (\_), periods (.)
  * **Restrictions**: No spaces, tabs, or newline characters
  * **Start/End**: Must start and end with letters or numbers only
</ParamField>

<RequestExample>
  ```bash cURL Request Example 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 Request Body (JSON format but sent as text/plain) theme={null}
  {
    "tokenId": [
      "user001a",
      "api.key.01", 
      "token-123-abc",
      "session_data_01"
    ]
  }
  ```
</RequestExample>

## Response

### Success Response (200)

<ResponseField name="success" type="Boolean">
  Operation success status
</ResponseField>

<ResponseField name="message" type="String">
  Operation result message
</ResponseField>

<ResponseField name="summary" type="Object">
  Summary information

  <Expandable title="summary properties">
    <ResponseField name="totalSubmitted" type="Number">
      Total number of tokens submitted
    </ResponseField>

    <ResponseField name="currentCount" type="Number">
      Total number of currently registered tokens
    </ResponseField>

    <ResponseField name="processed" type="Number">
      Number of tokens successfully processed
    </ResponseField>

    <ResponseField name="failed" type="Number">
      Number of failed tokens
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="details" type="Object">
  Detailed information (included only when failures occur)

  <Expandable title="details properties">
    <ResponseField name="failed" type="Array">
      List of failed tokens

      <Expandable title="failed array properties">
        <ResponseField name="tokenId" type="String">
          Failed token ID
        </ResponseField>

        <ResponseField name="error" type="String">
          Failure code
        </ResponseField>

        <ResponseField name="message" type="String">
          Failure message
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

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

  ```json Partial Failure 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>

### Error Response (400/500)

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

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

<ResponseField name="errorDetails" type="Object">
  Error details (optional)
</ResponseField>

<ResponseExample>
  ```json Token Format Error 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>

## Token Policy

### Limitations

<Warning>
  **Token Pool**: Maximum 100,000 per PID (error occurs when exceeded)
  **Per Request**: Maximum 500 token IDs
</Warning>

<Warning>
  **Important**: An error will occur when the token pool exceeds 100,000. To manage token count, you can utilize the following two methods:

  * Use the [DELETE Token Deletion API](/en/idcheck/api-reference/api-reference-guide/delete-token) to clean up unnecessary tokens in advance.
  * Enable the 'Token Id deletion condition setting' in the dashboard private mode settings for automatic deletion when tokens expire; used tokens are automatically deleted.
</Warning>

### Partial Handling

<Info>
  POST requests are processed partially for token IDs.
  Token IDs that already exist in the pool will be overwritten, and no separate duplication error is returned.
</Info>

**Example:**

* Token IDs existing in pool: `tokenA`, `tokenB`, `tokenC`
* POST request: `tokenA`, `tokenC`, `tokenD`
* Pool after request completion: `tokenA`, `tokenB`, `tokenC`, `tokenD`

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

<Tip>
  You can securely transmit sensitive token data through encryption settings. Consider enabling the encryption option for security in production environments.
</Tip>

<Tip>
  **Liveform QueryString Usage**: [https://form.argosidentity.com?pid=\{projectid}\&token=\{tokenid\_POSTed}](https://form.argosidentity.com?pid=\{projectid}\&token=\{tokenid_POSTed})
</Tip>

<Note>
  **Content-Type Notice**: For POST requests, when using `Content-Type: application/json` causes an error, set the header to `text/plain` instead.
</Note>