Authentication

The Wortfreunde API uses API keys to authenticate requests. This guide covers how to obtain and use your API credentials.

Getting Your API Key

1. Log in to your Wortfreunde Studio account
2. Navigate to Settings → API Tokens
3. Create a new key
4. Give your key a descriptive name (e.g., Production App or Development)
5. Copy the key - it won't be shown again

⚠️ Warnung

Important: Treat your API keys as passwords. Never commit them to version control or share them publicly.

Using Your API Key

Include your API key in all requests using the Authorization header:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.wortfreunde.ch/v1/channels

Header Authentication

For authentication, include your API key in the request header:

// JavaScript
const response = await fetch('https://api.wortfreunde.ch/v1/channels', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});

# Python
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.wortfreunde.ch/v1/channels',
    headers=headers
)

API Key Scopes

API keys can have different permission scopes:

Scope	Description
read:channels	Get a list of channels.
read:posts	Get a list of posts and their details.
read:media	Get details about related media.
write:posts	Publish posts and update their publication status.
write:examples	Import examples (e.g. LinkedIn posts via Chrome extension).
write:sso	Create one-time SSO login tokens for external authentication.

You can configure scopes when creating an API key in the Studio.

Best Practices

1. Use Environment Variables

Never hardcode API keys in your source code:

// ❌ Don't do this
const apiKey = 'wf_live_abc123xyz';

// ✅ Do this instead
const apiKey = process.env.WORTFREUNDE_API_KEY;

2. Rotate Keys Regularly

• Generate new API keys periodically
• Update your applications to use the new keys
• Revoke old keys once migration is complete

3. Use Different Keys for Different Environments

Create separate API keys for: - Development - Staging - Production

4. Monitor Key Usage

Track API key usage in the Studio dashboard to: - Detect unusual activity - Monitor rate limits - Audit access patterns

Error Handling

Authentication errors return appropriate HTTP status codes:

Status Code	Description
401	Invalid or missing API key
403	Valid key but insufficient permissions
429	Rate limit exceeded

Example error response:

{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid API key provided",
    "details": "The API key 'wf_live_...' is not valid"
  }
}

Testing Authentication

Test your authentication setup:

# Test with curl
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.wortfreunde.ch/v1/me

# Expected response
{
    "data": {
        "account": {
            "id": 3,
            "name": "Wertstifter GmbH"
        },
        "token": {
            "name": "Development Token",
            "scopes": [
                "read:channels",
                "read:posts",
                "read:media"
            ],
            "expires_at": "2027-03-09T09:53:43.348Z"
        }
    }
}