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

# Your First Request

> Install the Gatelit SDK, issue a signed token from your backend, and send your first chat request end-to-end.

This guide walks you through everything you need to go from zero to a working AI response using the Gatelit gateway.

<Steps>
  <Step title="Install the SDK">
    Install `@gatelit/sdk` in your project:

    ```bash theme={null}
    npm install @gatelit/sdk
    ```

    The SDK is ESM-first and ships TypeScript types. It works in browsers, Node.js 18+, and edge runtimes (Cloudflare Workers, Vercel Edge, etc.).
  </Step>

  <Step title="Issue signed tokens from your backend">
    Gatelit uses short-lived signed tokens to authenticate client requests. Your backend signs each token with your `GATELIT_SIGNING_SECRET` — the token is never stored, and expires after a configurable TTL (default: 60 seconds).

    Import `signToken` from `@gatelit/sdk/sign` in a server-side handler:

    <CodeGroup>
      ```ts Next.js API Route theme={null}
      // app/api/ai-token/route.ts
      import { signToken } from "@gatelit/sdk/sign"

      export async function GET(request: Request) {
        // Validate your session here — e.g. via NextAuth, Clerk, etc.
        const userId = "user_abc123"

        const token = await signToken(
          {
            sub: userId,
            ttl: 60, // token valid for 60 seconds
          },
          process.env.GATELIT_SIGNING_SECRET!,
        )

        return Response.json({ token })
      }
      ```

      ```ts Nuxt Server Route theme={null}
      // server/api/ai-token.get.ts
      import { signToken } from "@gatelit/sdk/sign"

      export default defineEventHandler(async (event) => {
        const user = await requireUser(event) // your auth middleware

        const token = await signToken(
          {
            sub: user.id,
            ttl: 60,
          },
          process.env.GATELIT_SIGNING_SECRET!,
        )

        return { token }
      })
      ```

      ```ts Express theme={null}
      // routes/ai-token.ts
      import { signToken } from "@gatelit/sdk/sign"
      import { Router } from "express"

      const router = Router()

      router.get("/ai-token", async (req, res) => {
        // Validate your session here
        const userId = req.user.id

        const token = await signToken(
          {
            sub: userId,
            ttl: 60,
          },
          process.env.GATELIT_SIGNING_SECRET!,
        )

        res.json({ token })
      })
      ```
    </CodeGroup>

    The `signToken` function uses the Web Crypto API (available natively in Node 18+ and all edge runtimes) and returns a compact dot-separated string you pass directly to the client.

    <Note>
      You can restrict a token to a specific model, cap its output tokens, and embed an org ID for provider key resolution. See the `SignedTokenOptions` type for the full set of options.
    </Note>
  </Step>

  <Step title="Create a GatelitClient">
    On the client side, instantiate `GatelitClient` with your gateway URL and a `getToken` function that fetches a fresh token from your backend endpoint:

    ```ts theme={null}
    import { GatelitClient } from "@gatelit/sdk"

    const client = new GatelitClient({
      gatewayUrl: "https://gateway.yourapp.com",
      getToken: async () => {
        const { token } = await fetch("/api/ai-token").then(r => r.json())
        return { token, scheme: "GatelitSigned" }
      },
    })
    ```

    `getToken` is called before every request. You should add token caching in your implementation to avoid an extra round-trip on every request.
  </Step>

  <Step title="Send your first chat request">
    Call `client.chat()` with a model in `provider/model-name` format and an array of messages:

    ```ts theme={null}
    const response = await client.chat({
      model: "openai/gpt-4o-mini",
      messages: [
        { role: "user", content: "What is the Gatelit gateway?" },
      ],
    })

    console.log(response.content)
    ```

    Supported model formats:

    | Provider  | Example model string                   |
    | --------- | -------------------------------------- |
    | OpenAI    | `openai/gpt-4o-mini`                   |
    | Anthropic | `anthropic/claude-3-5-sonnet-20241022` |
    | Google    | `google/gemini-2.0-flash-001`          |
    | Mistral   | `mistral/mistral-small-latest`         |
  </Step>

  <Step title="Handle the response">
    `client.chat()` returns a `ChatResponse` with the following shape:

    ```ts theme={null}
    interface ChatResponse {
      /** The assistant's response text */
      content: string
      /** Resolved model identifier in "provider/model-name" format */
      model: string
      /** Token usage for this request */
      usage: {
        inputTokens: number
        outputTokens: number
        totalTokens: number
      } | null
      /** Reason the model stopped generating — e.g. "stop", "length" */
      finishReason: string | null
      /** Gatelit-specific metadata */
      meta: {
        /** Use this ID to look up the request in the Gatelit dashboard */
        requestId: string
        /** The model that actually handled the request (may differ from requested if a fallback triggered) */
        model: string
      }
    }
    ```

    A complete example:

    ```ts theme={null}
    const response = await client.chat({
      model: "openai/gpt-4o-mini",
      messages: [
        { role: "system", content: "You are a helpful assistant." },
        { role: "user", content: "Explain recursion in one sentence." },
      ],
      maxTokens: 200,
    })

    console.log(response.content)
    // → "Recursion is when a function calls itself..."

    console.log(response.usage?.totalTokens)
    // → 42

    console.log(response.meta.requestId)
    // → "req_01j..."
    ```

    <Note>
      Every response includes an `x-gatelit-request-id` response header that matches `response.meta.requestId`. You can paste this ID into the Gatelit dashboard to look up the full request log, including token usage, latency, and model routing details.
    </Note>
  </Step>
</Steps>