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

# Stream Token API

> Generate a secure, single-use token for authenticating streaming workflow requests.

### Overview

This endpoint generates a short-lived, single-use token for the streaming endpoint. Tokens are stored securely in Redis and automatically expire after their TTL period. This is **step 1** of the two-step streaming flow.

### Endpoint

* **HTTP Method**: GET

* **URL**: `/api/v1/token`

### Features

<CardGroup cols={2}>
  <Card title="Single-Use Security" icon="key">
    Each token can only be used **once** — it is deleted from Redis after the first stream request.
  </Card>

  <Card title="Configurable TTL" icon="clock">
    Set a custom **time-to-live** between 1 and 300 seconds (default: 60s).
  </Card>

  <Card title="Bearer Key Auth" icon="lock">
    Tokens are generated under your **API key** — credits are charged to your organization.
  </Card>

  <Card title="Rate Limited" icon="gauge">
    Server-derived rate limiting ensures **fair usage** across all consumers.
  </Card>
</CardGroup>

### Authentication

Requires a Bearer token in the `Authorization` header.

```
Authorization: Bearer YOUR_API_KEY
```

### Request

**Query Parameters**

| Name | Required | Type   | Default | Description                       |
| ---- | -------- | ------ | ------- | --------------------------------- |
| ttl  | No       | number | 60      | Token lifetime in seconds (1–300) |

No body content is required for this GET request.

### Example Request

```bash theme={null}
curl --request GET \
     --url "https://aitutor-api.vercel.app/api/v1/token?ttl=60" \
     --header "Authorization: Bearer YOUR_API_KEY"
```

With a custom TTL of 5 minutes:

```bash theme={null}
curl --request GET \
     --url "https://aitutor-api.vercel.app/api/v1/token?ttl=300" \
     --header "Authorization: Bearer YOUR_API_KEY"
```

### Response

A successful response returns the token and its TTL:

```json theme={null}
{
  "success": true,
  "token": "pub_tok_a1b2c3d4e5f6",
  "ttl": 60
}
```

| Field   | Type    | Description                                         |
| ------- | ------- | --------------------------------------------------- |
| success | boolean | Always `true` on success                            |
| token   | string  | The single-use stream token (format: `pub_tok_...`) |
| ttl     | number  | Token lifetime in seconds                           |

**Response Headers**

| Header                | Description                  |
| --------------------- | ---------------------------- |
| x-ratelimit-limit     | Your rate limit per window   |
| x-ratelimit-remaining | Remaining requests in window |

### Error Responses

<AccordionGroup>
  <Accordion title="401 Unauthorized" icon="lock">
    Missing or invalid API key.

    ```json theme={null}
    {
      "error": "Unauthorized. Please provide a valid secret key.",
      "success": false
    }
    ```
  </Accordion>

  <Accordion title="402 Payment Required" icon="credit-card">
    No credits remaining on the account.

    ```json theme={null}
    {
      "error": "No credits remaining. Please add credits to continue using the service.",
      "success": false,
      "code": "invalid_billing"
    }
    ```
  </Accordion>

  <Accordion title="429 Too Many Requests" icon="shield-check">
    Rate limit exceeded.

    ```json theme={null}
    {
      "error": "Rate limit exceeded",
      "success": false
    }
    ```
  </Accordion>

  <Accordion title="500 Internal Server Error" icon="triangle-exclamation">
    Token generation failed.

    ```json theme={null}
    {
      "error": "Failed to create token, please try again or contact support.",
      "success": false,
      "code": "internal_server_error"
    }
    ```
  </Accordion>
</AccordionGroup>

### Code Examples

<AccordionGroup>
  <Accordion title="Python" icon="python">
    ```python theme={null}
    import requests

    url = "https://aitutor-api.vercel.app/api/v1/token?ttl=60"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
    }

    response = requests.get(url, headers=headers)
    token = response.json()["token"]
    print(token)
    ```
  </Accordion>

  <Accordion title="Node.js" icon="node-js">
    ```javascript theme={null}
    const response = await fetch(
      "https://aitutor-api.vercel.app/api/v1/token?ttl=60",
      {
        headers: {
          Authorization: "Bearer YOUR_API_KEY",
        },
      }
    );

    const { token } = await response.json();
    console.log(token);
    ```
  </Accordion>

  <Accordion title="cURL" icon="terminal">
    ```bash theme={null}
    curl --request GET \
         --url "https://aitutor-api.vercel.app/api/v1/token?ttl=60" \
         --header "Authorization: Bearer YOUR_API_KEY"
    ```
  </Accordion>
</AccordionGroup>

### Additional Notes

* **Single-Use**: The token is deleted from Redis after its first use in a stream request.

* **Auto-Expiry**: Tokens expire automatically after the TTL period — unused tokens do not count against your API quota.

* **Next Step**: Use this token as a query parameter on the [Stream Workflow](/docs/stream-workflow) endpoint to start receiving real-time responses.