Authentication

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:

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

Trial Token
Access Key
Google Sign-In
Bearer Token

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

curl -s -X POST https://api.xpoz.ai/api/trial/token \
  -H "Content-Type: application/json" \
  -d '{"source": "docs"}' | 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.

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

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 — still no credit card. Same API shape, nothing to rewrite.

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 and navigate to the dashboard. Your access key is available on the Get Token page at xpoz.ai/get-token.

Step 2: Use the key

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

export XPOZ_API_KEY=your-api-key

TypeScript
Python
CLI

import { XpozClient } from '@xpoz/xpoz';

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

await client.connect();

from xpoz import XpozClient

client = XpozClient("your-api-key")

export XPOZ_API_KEY=your-api-key
xpoz-cli twitter get_user --identifier elonmusk

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

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

Connect from your client

Claude Code
N8N
Any HTTP Client

claude mcp add xpoz-mcp https://mcp.xpoz.ai/mcp \
  -t http \
  -H "Authorization: Bearer YOUR_API_KEY"

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.

Include the bearer token in the Authorization header:

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}'

Getting Started

Guides

Authentication

Credential precedence

Step 1: Generate a free token

Step 2: Use it as your API key

Access Key authentication

Step 1: Get your access key

Step 2: Use the key

Bearer token authentication

Get your access key

Connect from your client

Next steps

Quickstart

MCP Tools

​Credential precedence

​Instant access — no sign-up

​Step 1: Generate a free token

​Step 2: Use it as your API key

​Access Key authentication

​Step 1: Get your access key

​Step 2: Use the key

​Google Sign-In

​How it works

​Bearer token authentication

​Get your access key

​Connect from your client

​Next steps

Quickstart

MCP Tools

Credential precedence

Instant access — no sign-up

Step 1: Generate a free token

Step 2: Use it as your API key

Access Key authentication

Step 1: Get your access key

Step 2: Use the key

Google Sign-In

How it works

Bearer token authentication

Get your access key

Connect from your client

Next steps