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

# Authentication

> How token-based authentication works on the Chainworks API over both Socket.IO and HTTP, including required credentials.

The Chainworks API uses token-based authentication. The same token works on both transports; only where you put it differs.

* **Socket.IO** sends the token once in the connection handshake (`auth: { token }`).
* **HTTP** sends the token on every request in the `Authorization` header, as the raw token with no `Bearer` prefix.

## Authentication Flow

1. Obtain your API credentials (API URL and Auth Token)
2. Provide the token: in the Socket.IO handshake, or in the HTTP `Authorization` header
3. The server validates your token
4. If valid, you can start making API requests

## Connecting with Credentials

<Tabs>
  <Tab title="Socket.IO">
    The token is validated once during the handshake.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      import { io } from "socket.io-client";

      const socket = io(CHAINWORKS_API_URL, {
        transports: ["websocket"],
        auth: {
          token: CHAINWORKS_API_AUTH_TOKEN,
        },
      });
      ```

      ```python Python theme={null}
      import socketio

      sio = socketio.Client()

      sio.connect(
          CHAINWORKS_API_URL,
          transports=["websocket"],
          auth={"token": CHAINWORKS_API_AUTH_TOKEN}
      )
      ```
    </CodeGroup>
  </Tab>

  <Tab title="HTTP">
    The token is validated on every request via the `Authorization` header (raw token, no `Bearer` prefix). Requests use `Content-Type: application/json`.

    <CodeGroup>
      ```typescript TypeScript theme={null}
      const res = await fetch(`${CHAINWORKS_API_URL}/svm/token/meta`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: CHAINWORKS_API_AUTH_TOKEN,
        },
        body: JSON.stringify({ chain: "sol", token: "..." }),
      });
      ```

      ```python Python theme={null}
      import requests

      res = requests.post(
          f"{CHAINWORKS_API_URL}/svm/token/meta",
          headers={"Authorization": CHAINWORKS_API_AUTH_TOKEN},
          json={"chain": "sol", "token": "..."},
      )
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Environment Variables

We recommend storing your credentials in environment variables:

```bash .env theme={null}
CHAINWORKS_API_URL=https://api.chainworks.co
CHAINWORKS_API_AUTH_TOKEN=your-secret-token
```

<Tabs>
  <Tab title="Socket.IO">
    ```typescript theme={null}
    const socket = io(process.env.CHAINWORKS_API_URL!, {
      transports: ["websocket"],
      auth: {
        token: process.env.CHAINWORKS_API_AUTH_TOKEN!,
      },
    });
    ```
  </Tab>

  <Tab title="HTTP">
    ```typescript theme={null}
    const res = await fetch(`${process.env.CHAINWORKS_API_URL}/svm/token/meta`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: process.env.CHAINWORKS_API_AUTH_TOKEN!,
      },
      body: JSON.stringify({ chain: "sol", token: "..." }),
    });
    ```
  </Tab>
</Tabs>

## Connection Events (Socket.IO)

These lifecycle events apply to the Socket.IO transport. HTTP is stateless and has no connection events, so handle errors per request from the response instead.

Handle connection lifecycle events to ensure robust operation:

```typescript theme={null}
socket.on("connect", () => {
  console.log("Connected successfully");
  // Start making API requests
});

socket.on("connect_error", (error) => {
  console.error("Connection error:", error.message);
  // Handle authentication failures
  if (error.message.includes("unauthorized")) {
    console.error("Invalid API token");
  }
});

socket.on("disconnect", (reason) => {
  console.log("Disconnected:", reason);
  // Handle reconnection if needed
});
```

## Reconnection (Socket.IO)

Socket.IO automatically handles reconnection. You can configure the behavior:

```typescript theme={null}
const socket = io(CHAINWORKS_API_URL, {
  transports: ["websocket"],
  auth: {
    token: CHAINWORKS_API_AUTH_TOKEN,
  },
  reconnection: true,
  reconnectionAttempts: 5,
  reconnectionDelay: 1000,
  reconnectionDelayMax: 5000,
});
```

## Security Best Practices

1. **Never expose tokens in client-side code** - Use server-side proxies for browser applications
2. **Rotate tokens regularly** - Contact us to regenerate compromised tokens
3. **Use environment variables** - Never hardcode tokens in source code
4. **Monitor usage** - Track API calls to detect unauthorized access

## Rate Limits

API rate limits depend on your subscription tier. Contact us for details about rate limits and quotas.

## Next Steps

* [Quick Start](/quickstart) - Get started with your first request
* [EVM Endpoints](/evm/overview) - Explore Ethereum, Base, and BSC endpoints
* [SVM Endpoints](/svm/overview) - Explore Solana endpoints