> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trelent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List tokens

> View existing tokens with optional filtering by ID, issuer, or subject.

List tokens registered in the system. Requires `token:list` or `token:*` permission. By default, only valid (non-expired, non-revoked) tokens are returned.

## Query parameters

<ParamField query="token_id" type="uuid">
  Filter by specific token ID.
</ParamField>

<ParamField query="issuer" type="string">
  Filter by token issuer.
</ParamField>

<ParamField query="subject" type="string">
  Filter by token subject.
</ParamField>

<ParamField query="include_invalid" type="boolean" default="false">
  Include expired and revoked tokens in results.
</ParamField>

## List all valid tokens

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={null}
    // TODO: Add TypeScript SDK example for listing tokens
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # TODO: Add Python SDK example for listing tokens
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "${API_URL}/v1/token/list" \
      -H "Authorization: Bearer ${API_TOKEN}"
    ```
  </Tab>
</Tabs>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "tokens": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "issuer": "trelent-data-ingestion",
        "subject": "my-service",
        "created_at": "2024-12-01T10:00:00Z",
        "expires_at": "2024-12-02T10:00:00Z",
        "revoked_at": null,
        "is_valid": true
      }
    ]
  }
  ```
</ResponseExample>

## Response fields

<ResponseField name="tokens" type="array">
  List of token information objects.

  <Expandable title="Token object fields">
    <ResponseField name="id" type="uuid">
      Unique token identifier (JTI).
    </ResponseField>

    <ResponseField name="issuer" type="string">
      Token issuer claim.
    </ResponseField>

    <ResponseField name="subject" type="string">
      Token subject claim.
    </ResponseField>

    <ResponseField name="created_at" type="datetime">
      When the token was generated.
    </ResponseField>

    <ResponseField name="expires_at" type="datetime">
      When the token expires.
    </ResponseField>

    <ResponseField name="revoked_at" type="datetime">
      When the token was revoked, or `null` if still active.
    </ResponseField>

    <ResponseField name="is_valid" type="boolean">
      Whether the token is currently valid (not expired and not revoked).
    </ResponseField>
  </Expandable>
</ResponseField>

## Filter by subject

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "${API_URL}/v1/token/list?subject=my-service&include_invalid=true" \
      -H "Authorization: Bearer ${API_TOKEN}"
    ```
  </Tab>
</Tabs>