authentication.mdx

title	Authentication
description	Authenticate with Xpoz using an access key, Google sign-in, or bearer token.

Every request to Xpoz requires authentication. Choose the method that fits your use case:

Method	Best for	Complexity
Trial Token	Instant access, no sign-up needed	Simplest
Access Key	SDKs, CLI, scripts, quick prototyping	Simplest
Google Sign-In	Claude Desktop, browser-based clients	Automatic
Bearer Token	Claude Code, N8N, programmatic MCP access	One-time setup

Credential precedence

When multiple credentials are available, Xpoz resolves them in this order:

1. Explicit parameter passed to the client constructor (apiKey / api_key)
2. Environment variable (XPOZ_API_KEY)
3. Stored configuration (from CLI auth login or prior sign-in)

## Instant access — no sign-up

Get a working API key in two HTTP calls — no signup, no approval, no waiting. Perfect for agents that need social media data right now.

### Step 1: Generate a free token

```bash
curl -s -X POST https://api.xpoz.ai/api/trial/token \
  -H "Content-Type: application/json" \
  -d '{"source": "<how you discovered xpoz>"}' | jq -r .data.accessKey
# -> TRIAL...  (valid 5 days)
```

### Step 2: Use it as your API key

Pass the `TRIAL...` token exactly like an access key — as the SDK `apiKey`, the `XPOZ_API_KEY` env var, or a bearer token. All read tools work immediately across all four platforms.

```bash
export XPOZ_API_KEY=TRIAL...
xpoz-cli twitter get_user --identifier elonmusk
```

<Note>
  Instant access tokens return up to 5 results per call. For full result sets, pagination, CSV export, and live crawling, [get a free access key](https://xpoz.ai/get-token) — still no credit card. Same API shape, nothing to rewrite.
</Note>

## Access Key authentication

The simplest way to authenticate. Get your key and start querying immediately.

### Step 1: Get your access key

Sign up at [xpoz.ai](https://xpoz.ai) and navigate to the dashboard. Your access key is available on the **Get Token** page at [xpoz.ai/get-token](https://xpoz.ai/get-token).

### Step 2: Use the key

Pass the key directly or set it as an environment variable:

```bash
export XPOZ_API_KEY=your-api-key
```

<Tabs>
  <Tab title="TypeScript">
    ```typescript
    import { XpozClient } from '@xpoz/xpoz';

    const client = new XpozClient({ apiKey: 'your-api-key' });

    await client.connect();
    ```
  </Tab>
  <Tab title="Python">
    ```python
    from xpoz import XpozClient

    client = XpozClient("your-api-key")
    ```
  </Tab>
  <Tab title="CLI">
    ```bash
    export XPOZ_API_KEY=your-api-key
    xpoz-cli twitter get_user --identifier elonmusk
    ```
  </Tab>
</Tabs>

<Note>
  Never commit access keys to version control. Use environment variables or a secrets manager in production.
</Note>

## Google Sign-In

When you connect via Claude Desktop or other browser-based MCP clients, authentication happens automatically through Google Sign-In.

### How it works

1. Your MCP client (e.g., Claude Desktop) initiates the sign-in flow when connecting to Xpoz
2. A Google sign-in prompt appears in your browser
3. After signing in, the connection is established automatically
4. All subsequent requests are authenticated — no manual token management required

<Tip>
  This is the recommended method for Claude Desktop. Just add the Xpoz MCP server and the sign-in flow handles everything.
</Tip>

See [Installation](/mcp/installation) for step-by-step setup with Claude Desktop.

## Bearer token authentication

For programmatic access from Claude Code, N8N, or any HTTP client. Pass your access key as a bearer token in the `Authorization` header.

### Get your access key

Sign up at [xpoz.ai](https://xpoz.ai) and copy your access key from the dashboard.

### Connect from your client

<Tabs>
  <Tab title="Claude Code">
    ```bash
    claude mcp add xpoz-mcp https://mcp.xpoz.ai/mcp \
      -t http \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```
  </Tab>
  <Tab title="N8N">
    Create an **AI Agent** node and add a **Tool** > **MCP Client Tool**:

    - **Endpoint**: `https://mcp.xpoz.ai/mcp`
    - **Server Transport**: HTTP Streamable
    - **Authentication Type**: Bearer Auth
    - **Credential for Bearer Auth**: Your access key

    If you can see the tools list, you are connected.
  </Tab>
  <Tab title="Any HTTP Client">
    Include the bearer token in the `Authorization` header:

    ```bash
    curl -X POST https://mcp.xpoz.ai/mcp \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"getTwitterUser","arguments":{"identifier":"elonmusk","identifierType":"username"}},"id":1}'
    ```
  </Tab>
</Tabs>

Next steps

Start querying with your credentials Browse all 48 available tools