Authentication & Configuration

Overview

The Mention API client supports multiple authentication and configuration methods to fit different use cases. This guide covers all available options for initializing and configuring your client.

Quick Start

The simplest way to get started is with a direct access token:

Sync
Async

from mention import MentionClient

client = MentionClient(access_token="your-access-token-here")

from mention import AsyncMentionClient

client = AsyncMentionClient(access_token="your-access-token-here")

Configuration Methods

Environment Variables

The recommended approach for production applications is to use environment variables with the MentionConfig.from_env() method.

Setting Up Environment Variables

Create a .env file in your project root:

MENTION_ACCESS_TOKEN=your-access-token-here
MENTION_ACCOUNT_ID=your-account-id
MENTION_BASE_URL=https://api.mention.net/api
MENTION_TIMEOUT=30.0
MENTION_MAX_RETRIES=3
MENTION_RETRY_DELAY=1.0

Only MENTION_ACCESS_TOKEN is required. All other variables have sensible defaults.

Using Configuration with Client

Sync
Async

from mention import MentionClient, MentionConfig

# Load configuration from environment variables
config = MentionConfig.from_env()

# Create client from configuration
client = MentionClient.from_config(config)

# Use the client
account = client.get_account_me()
print(f"Account: {account.name}")

import asyncio
from mention import AsyncMentionClient, MentionConfig

async def main():
    # Load configuration from environment variables
    config = MentionConfig.from_env()

    # Create async client from configuration
    client = AsyncMentionClient.from_config(config)

    # Use the client
    account = await client.get_account_me()
    print(f"Account: {account.name}")

    await client.close()

asyncio.run(main())

Custom Environment File

You can specify a custom .env file location:

from mention import MentionConfig

config = MentionConfig.from_env(env_file="/path/to/custom.env")

Custom Environment Variable Prefix

By default, the client looks for variables prefixed with MENTION_. You can customize this:

config = MentionConfig.from_env(prefix="MY_APP_")

With this configuration, set environment variables like:

MY_APP_ACCESS_TOKEN=your-token
MY_APP_ACCOUNT_ID=your-account-id

Direct Configuration

For programmatic configuration, create a MentionConfig instance directly:

from mention import MentionClient, MentionConfig

config = MentionConfig(
    access_token="your-access-token",
    account_id="your-account-id",
    base_url="https://api.mention.net/api",
    timeout=30.0,
    max_retries=3,
    retry_delay=1.0
)

client = MentionClient.from_config(config)

Configuration Options

The MentionConfig dataclass supports the following options:

Parameter	Type	Default	Description
`access_token`	`str`	Required	OAuth2 access token for authentication
`account_id`	`str \| None`	`None`	Default account ID for operations
`base_url`	`str`	`https://api.mention.net/api`	Base URL for the Mention API
`timeout`	`float`	`30.0`	Request timeout in seconds
`max_retries`	`int`	`3`	Maximum retry attempts for failed requests
`retry_delay`	`float`	`1.0`	Base delay between retries (uses exponential backoff)

Advanced Configuration

Context Manager Pattern

Both sync and async clients support context managers for automatic resource cleanup:

Sync
Async

from mention import MentionClient

with MentionClient(access_token="your-token") as client:
    account = client.get_account_me()
    alerts = client.get_alerts(account.id)
    print(f"Found {len(alerts.alerts)} alerts")
# Client is automatically closed after the with block

import asyncio
from mention import AsyncMentionClient

async def main():
    async with AsyncMentionClient(access_token="your-token") as client:
        account = await client.get_account_me()
        alerts = await client.get_alerts(account.id)
        print(f"Found {len(alerts.alerts)} alerts")
    # Client is automatically closed after the async with block

asyncio.run(main())

Per-Account Configuration

If you work with multiple accounts, you can create account-specific configurations:

from mention import MentionConfig

base_config = MentionConfig.from_env()

# Create account-specific configurations
account1_config = base_config.with_account("account-id-1")
account2_config = base_config.with_account("account-id-2")

# Use with clients
client1 = MentionClient.from_config(account1_config)
client2 = MentionClient.from_config(account2_config)

Custom Client Initialization

For fine-grained control, initialize the client directly with custom parameters:

from mention import MentionClient

client = MentionClient(
    access_token="your-token",
    base_url="https://api.mention.net/api",
    timeout=60.0,        # Longer timeout for slow operations
    max_retries=5,       # More retries for unreliable networks
    retry_delay=2.0      # Longer delay between retries
)

Best Practices

Never Hardcode Credentials

Always use environment variables or secure secret management systems. Never commit access tokens to version control.

# ❌ Bad
client = MentionClient(access_token="abc123...")

# ✅ Good
config = MentionConfig.from_env()
client = MentionClient.from_config(config)

Use Context Managers

Always use context managers to ensure proper cleanup of HTTP connections:

# ✅ Good
with MentionClient.from_config(config) as client:
    # Use client
    pass
# Resources automatically cleaned up

Configure Timeouts Appropriately

Set timeouts based on your use case:

Interactive applications: 10-30 seconds
Background processing: 60+ seconds
Streaming operations: 120+ seconds

# For long-running operations
config = MentionConfig(
    access_token=token,
    timeout=120.0,
    max_retries=5
)

Handle Multiple Accounts Efficiently

Create configurations once and reuse them:

base_config = MentionConfig.from_env()

accounts = ["account-1", "account-2", "account-3"]
clients = {
    account_id: MentionClient.from_config(
        base_config.with_account(account_id)
    )
    for account_id in accounts
}

Obtaining an Access Token

To use the Mention API, you need an OAuth2 access token. Here’s how to obtain one:

Log in to your Mention account
Navigate to Settings → API
Generate a new access token
Store it securely in your environment variables

Access tokens grant full access to your Mention account. Treat them like passwords and never expose them in client-side code or public repositories.

Get Started

Guides

CLI

Overview

Quick Start

Configuration Methods

Environment Variables

Setting Up Environment Variables

Using Configuration with Client

Custom Environment File

Custom Environment Variable Prefix

Direct Configuration

Configuration Options

Advanced Configuration

Context Manager Pattern

Per-Account Configuration

Custom Client Initialization

Best Practices

Obtaining an Access Token

Next Steps

Sync vs Async

Error Handling

Build docs developers (and LLMs) love

Get Started

Guides

CLI

​Overview

​Quick Start

​Configuration Methods

​Environment Variables

​Setting Up Environment Variables

​Using Configuration with Client

​Custom Environment File

​Custom Environment Variable Prefix

​Direct Configuration

​Configuration Options

​Advanced Configuration

​Context Manager Pattern

​Per-Account Configuration

​Custom Client Initialization

​Best Practices

​Obtaining an Access Token

​Next Steps

Sync vs Async

Error Handling

Build docs developers (and LLMs) love

Overview

Quick Start

Configuration Methods

Environment Variables

Setting Up Environment Variables

Using Configuration with Client

Custom Environment File

Custom Environment Variable Prefix

Direct Configuration

Configuration Options

Advanced Configuration

Context Manager Pattern

Per-Account Configuration

Custom Client Initialization

Best Practices

Obtaining an Access Token

Next Steps