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

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

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

Hilfe