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

# Token expired

> This event is triggered when a Token ID expires according to the configured expiration conditions. You can manage tokens based on usage count or time through Token Expiration settings, and webhooks are automatically sent when tokens expire. This allows you to track token lifecycle and prevent token reuse issues.

<Note>
  * Token ID expiration webhooks are only sent when Token Expiration settings are enabled in your project.
  * Token expiration can be configured as count-based or time-based.
</Note>

## Token ID types and expiration concepts

### Pre-registered token

A method where your system generates Token IDs in advance.

<Info>
  * Tokens expire immediately after a single submission.
  * An explicit expiration concept exists.
</Info>

### Non-registered token

A method that uses tokens without pre-generation.

<Info>
  * Tokens do not have an explicit expiration.
  * Validity is verified based on previous usage at the time of use.
</Info>

## Token expiration settings

Webhook delivery depends on whether Token Expiration settings are enabled in your project.

<Tabs>
  <Tab title="Count-based">
    Manages token expiration based on usage count.

    **Example**: Expires after 1 use
  </Tab>

  <Tab title="Time-based">
    Manages token expiration based on time.

    **Example**: Expires after 24 hours
  </Tab>
</Tabs>

## Webhook examples

<CodeGroup>
  ```json token-expired-count-based.json theme={null}
  {
    "webhook_trigger": "token_expired",
    "token_id": "tok_abc123def456",
    "expired_condition": "count",
    "expired_at": "2025-11-12T02:23:13.588Z",
    "service": "idCheck"
  }
  ```

  ```json token-expired-time-based.json theme={null}
  {
    "webhook_trigger": "token_expired",
    "token_id": "tok_xyz789ghi012",
    "expired_condition": "time",
    "expected_expired_at": "2025-11-12T02:23:13.588Z",
    "service": "idCheck"
  }
  ```
</CodeGroup>

## Response fields

<ResponseField name="webhook_trigger" type="string">
  Webhook trigger type - `token_expired` indicates that the Token ID has expired
</ResponseField>

<ResponseField name="token_id" type="string">
  The expired Token ID
</ResponseField>

<ResponseField name="expired_condition" type="string">
  The configured expiration validation condition

  * `count`: Count-based expiration
  * `time`: Time-based expiration
</ResponseField>

<ResponseField name="service" type="string">
  Target service - `idCheck` (ID check main pipeline)
</ResponseField>

<ResponseField name="expired_at" type="string">
  Expiration timestamp (ISO 8601 format)

  <Info>
    Only included when `expired_condition` is `count`. Indicates the exact time when the token expired.
  </Info>
</ResponseField>

<ResponseField name="expected_expired_at" type="string">
  Expected expiration timestamp (ISO 8601 format)

  <Info>
    Only included when `expired_condition` is `time`. Indicates when the token was scheduled to expire.
  </Info>
</ResponseField>

## Use cases

Token ID expiration webhooks are useful in the following scenarios:

<AccordionGroup>
  <Accordion title="Prevent token reuse">
    Detect expired tokens to block reuse attempts and log security events.
  </Accordion>

  <Accordion title="Track service logic">
    Track token lifecycle to analyze user flows and improve service quality.
  </Accordion>

  <Accordion title="Automated token management">
    Automatically generate new tokens or send notifications to users based on expiration events.
  </Accordion>
</AccordionGroup>

<Tip>
  Leveraging Token ID expiration webhooks can significantly enhance the security and traceability of your token-based flows.
</Tip>