> ## 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 (토큰 만료)

> 이 이벤트는 Token ID가 설정된 만료 조건에 따라 만료될 때 트리거됩니다. Token Expiration 설정을 통해 사용 횟수 또는 시간 기반으로 토큰을 관리할 수 있으며, 토큰이 만료되면 자동으로 웹훅이 발송됩니다. 이를 통해 토큰의 수명 주기를 추적하고 재사용 문제를 방지할 수 있습니다.

<Note>
  * Token ID 만료 웹훅은 프로젝트의 Token Expiration 설정이 활성화된 경우에만 발송됩니다.
  * 토큰 만료는 사용 횟수 기반(count-based) 또는 시간 기반(time-based)으로 설정할 수 있습니다.
</Note>

## Token ID 종류와 만료 개념

### 사전등록 토큰 (Pre-registered Token)

고객 시스템이 사전에 Token ID를 생성하는 방식입니다.

<Info>
  * 1회 제출되면 즉시 만료(Expired) 처리됩니다.
  * 명시적인 만료 개념이 존재합니다.
</Info>

### 비등록 토큰 (Non-registered Token)

토큰 생성 없이 사용하는 방식입니다.

<Info>
  * 토큰 자체에 명시적 만료가 없습니다.
  * 사용 시점 기준으로 이전 사용 여부 및 유효성을 검증합니다.
</Info>

## Token Expiration 설정 조건

웹훅 발송 여부는 프로젝트의 Token Expiration 설정 활성화 여부에 따라 결정됩니다.

<Tabs>
  <Tab title="Count-based">
    사용 횟수 기반으로 토큰 만료를 관리합니다.

    **예시**: 1회 사용 후 만료
  </Tab>

  <Tab title="Time-based">
    시간 기반으로 토큰 만료를 관리합니다.

    **예시**: 24시간 이후 만료
  </Tab>
</Tabs>

## 웹훅 예시

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

## 응답 필드

<ResponseField name="webhook_trigger" type="string">
  웹훅 트리거 유형 - `token_expired`는 Token ID가 만료되었음을 의미
</ResponseField>

<ResponseField name="token_id" type="string">
  만료된 Token ID
</ResponseField>

<ResponseField name="expired_condition" type="string">
  설정된 만료 검증 조건

  * `count`: 사용 횟수 기반 만료
  * `time`: 시간 기반 만료
</ResponseField>

<ResponseField name="service" type="string">
  대상 서비스 - `idCheck` (ID check 메인 파이프라인)
</ResponseField>

<ResponseField name="expired_at" type="string">
  만료된 시각 (ISO 8601 형식)

  <Info>
    `expired_condition`이 `count`인 경우에만 포함됩니다. 토큰이 실제로 만료된 정확한 시각을 나타냅니다.
  </Info>
</ResponseField>

<ResponseField name="expected_expired_at" type="string">
  만료 예정 시각 (ISO 8601 형식)

  <Info>
    `expired_condition`이 `time`인 경우에만 포함됩니다. 토큰이 만료될 예정이었던 시각을 나타냅니다.
  </Info>
</ResponseField>

## 사용 사례

Token ID 만료 웹훅은 다음과 같은 상황에서 유용합니다:

<AccordionGroup>
  <Accordion title="토큰 재사용 방지">
    만료된 토큰을 감지하여 재사용 시도를 차단하고, 보안 이벤트를 기록할 수 있습니다.
  </Accordion>

  <Accordion title="서비스 로직 추적">
    토큰의 수명 주기를 추적하여 사용자 플로우를 분석하고, 서비스 품질을 개선할 수 있습니다.
  </Accordion>

  <Accordion title="자동화된 토큰 관리">
    만료 이벤트를 기반으로 새로운 토큰을 자동 생성하거나, 사용자에게 알림을 전송할 수 있습니다.
  </Accordion>
</AccordionGroup>

<Tip>
  Token ID 만료 웹훅을 활용하면 토큰 기반 플로우의 보안성과 추적 가능성을 크게 향상시킬 수 있습니다.
</Tip>