Managing a fleet of automated scripts on Wikipedia used to mean juggling hundreds of username/password pairs. If one leaked, your entire infrastructure was at risk. Today, the standard approach relies on OAuth 2.0, a protocol that separates identity from action. This guide breaks down how to set up secure authentication for your bots, manage granular permissions, and avoid the common pitfalls that lead to IP bans or account locks.
Why Switch from Passwords to OAuth?
The old method involved storing plaintext credentials in config files or environment variables. It’s simple, but fragile. If you deploy a script on a shared server, those passwords are exposed. With OAuth, you use a temporary access token instead of a password. The token has a limited scope and expiration date. If it leaks, you can revoke it without changing the main account password.
For large-scale operations, this is critical. Imagine running 50 different maintenance bots. Each one needs specific rights-some edit pages, others upload images, and some just read data. OAuth allows you to grant each bot only what it needs. This follows the principle of least privilege, reducing the blast radius if a script goes rogue.
Understanding the Core Components
To implement this, you need to understand three key entities: the User Agent, the Authorization Server, and the Resource Server.
- User Agent: Your bot script (e.g., Python with the requests library).
- Authorization Server: In this context, it’s the MediaWiki platform itself, which issues tokens.
- Resource Server: The MediaWiki API endpoints that your bot calls to perform actions.
The flow works like this: Your bot asks the authorization server for permission. The user (or an admin) approves it. The server gives back a unique code. Your bot exchanges that code for an access token. Finally, your bot uses that token to talk to the API.
Step-by-Step Implementation Guide
Setting this up requires a few precise steps. Here is the logical flow for a standard Python-based bot.
- Create an Application: Go to Special:OAuthManageListClients on the target wiki. Register your app and note the
client_idandclient_secret. - Generate a Token:** Use a helper script to initiate the flow. You will be redirected to a login page where you authorize the specific scopes (e.g.,
wikibase-edit,read). - Store the Credentials:** Save the resulting
access_tokenandrefresh_token. Never store these in version control. - Make Requests:** Add the token to the header of your API calls using the format
Authorization: Bearer <token>.
Most modern libraries handle the exchange automatically. For example, the mediawikiapi Python package includes built-in support for OAuth flows, saving you from writing raw HTTP requests for token management.
Managing Scopes and Permissions
This is where most admins get tripped up. Scopes define exactly what a bot can do. Be overly broad, and you risk accidental damage. Be too narrow, and your bot fails silently.
| Scope Name | Description | Risk Level |
|---|---|---|
read |
Access public data without editing | Low |
write |
Edit pages and create new ones | Medium |
delete |
Delete pages or revisions | High |
upload |
Add files to the repository | Medium |
admin |
Full administrative rights | Critical |
A good rule of thumb: start with read and write only. Add delete only if absolutely necessary, and never grant admin to a general-purpose bot unless it’s a dedicated maintenance tool run by a trusted human.
Handling Token Expiration and Refresh
Access tokens aren’t forever. They expire after a set period (often 14 days on English Wikipedia). When they do, your bot stops working. This is where the refresh_token comes in. It’s a long-lived key that lets you request a new access token without asking the user to log in again.
You should build a background task that checks token expiry daily. If the token expires within 24 hours, use the refresh token to get a new pair. If the refresh token also fails, trigger an alert so a human can re-authorize the bot manually. Automating this prevents downtime during critical maintenance windows.
Best Practices for Production Bots
Running bots at scale requires more than just correct code. Consider these operational tips:
- Rate Limiting: Respect the API’s rate limits. Too many requests per second can trigger a temporary IP block. Use exponential backoff when you hit a 429 status code.
- Logging: Log every API call with the timestamp and result. This helps debug why a specific edit failed.
- Separation of Concerns: Keep your authentication logic separate from your business logic. This makes it easier to swap out auth providers or update tokens without touching core code.
- Secret Management: Use environment variables or a secrets manager like HashiCorp Vault. Avoid hardcoding secrets in scripts.
Troubleshooting Common Issues
If your bot suddenly stops working, check these three things first:
- Token Scope Mismatch: Did you recently change the bot’s tasks? If it now tries to delete a page but only has
writescope, it will fail with a 403 error. - Expired Refresh Token: If the bot hasn’t run in over 30 days, the refresh token might have expired. Re-authenticate manually.
- API Changes: MediaWiki updates occasionally. Check the release notes for any changes to the OAuth endpoint parameters.
Do I need OAuth for small personal bots?
Not necessarily. For a single, low-risk bot that runs locally, a basic API key or session cookie might suffice. However, OAuth is recommended even for small projects because it reduces security overhead and aligns with community best practices.
Can multiple bots share the same OAuth token?
Technically yes, but it’s not advised. Sharing tokens makes it hard to track which bot made a specific edit. It also means revoking one bot’s access affects all of them. Assign a unique client ID and token to each distinct bot instance.
What happens if I lose my refresh token?
You’ll need to go through the full authorization flow again. This involves logging into the wiki and granting permissions anew. To prevent this, back up your tokens securely outside of your code repository.
Is OAuth supported on all Wikimedia projects?
Yes, all major Wikimedia projects including English Wikipedia, Wikidata, and Commons support OAuth via the MediaWiki extension. Smaller community wikis may vary, so always check their local documentation.
How often should I rotate my OAuth tokens?
You don’t need to rotate them manually unless you suspect a leak. The automatic refresh process handles rotation. However, if you change the bot’s scope or role, it’s good practice to revoke the old token and issue a new one.
