Documentation menu
Authentication
Use your account credentials (username in lowercase) and tokens to manage your account programmatically. Wikimedia Enterprise APIs use JWT authentication passed in the header: all requests must be made over HTTPS and pass a Bearer access token in the Authorization header. Without it, your request returns a 401 - Unauthorized error. Use the Login endpoint to receive your tokens, then use the Refresh Token and Revoke Token endpoints to manage them. Your account password can also be managed with the associated endpoints referenced in this document.
Authentication at a glance
- Base URL:
https://auth.enterprise.wikimedia.com - Formats: JSON
- Tokens: access + ID tokens last 24 hours; refresh tokens last 90 days
- Access: included with every account
Token lifecycle
There are two ways to get an access token. You can copy an access token from your dashboard and keep it in a terminal variable, as shown in the Getting Started guide. A copied access token lasts 24 hours. When it expires, copy a new one from your dashboard. Code that runs longer than a day should contain logic to let it log in and refresh its own tokens:
- Call Login with your username and password. It returns an access token, which lasts 24 hours, and a refresh token, which lasts 90 days. Send the access token with every request. Login also returns an ID token, which API requests don't use.
- Store the access token and refresh token where other programs on the machine can't read them, such as your operating system's keychain or your platform's secrets manager, not a
.envfile. - Before the access token expires, call Refresh Token with your username and refresh token to get a new access token. Your refresh token stays the same. Refresh instead of logging in again each day.
- After 90 refreshes or 90 days, whichever comes first, the refresh token stops working. Call Login again to get a new one.
If a refresh token leaks, call Revoke Token with it to revoke the access tokens it issued.
Authentication worked example
Send the username (all lowercase) and password you created at signup to the Login endpoint to receive your tokens. The response contains your ID, access, and refresh tokens; pass the access_token as the Bearer token in the Authorization header of every API request.
curl -L https://auth.enterprise.wikimedia.com/v1/login -H "Content-Type: application/json" -d '{"username":"yourusername", "password":"secret"}'{ "id_token": "string", "access_token": "string", "refresh_token": "string", "expires_in": 86400}Before the access token expires, send your username and refresh_token to the Refresh Token endpoint. The response contains a new access token and ID token; keep using the refresh token from login.
curl -L https://auth.enterprise.wikimedia.com/v1/token-refresh -H "Content-Type: application/json" -d '{"username":"yourusername", "refresh_token":"your-refresh-token"}'{ "id_token": "string", "access_token": "string", "expires_in": 86400}Your credentials carry many privileges related to your account, so be careful to keep them secure. Do not share your credentials in publicly accessible areas such as GitHub, client-side code, etc.
Managing tokens and passwords
/v1/loginReceive auth tokens by providing a username and passwordPOST/v1/token-refreshReceive auth tokens by providing a refresh tokenPOST/v1/token-revokeRevoke all access tokens generated by a refresh tokenPOST/v1/forgot-passwordStart the forgot-password flow for a given userPOST/v1/forgot-password-confirmChange a user password as part of the forgot-password flowPOST/v1/change-passwordReplace an old user password with a new passwordPOST/v1/new-password-requiredRespond to a new-password-required challengePOST
Forgot Password sends a confirmation code by email. Use that code as input for the Forgot Password Confirmation endpoint to reset your password. New Password Required answers a NEW_PASSWORD_REQUIRED challenge with your username, session token, and new password as input.
If you're a Wikimedia community member, see the Access section on Meta-Wiki for other ways to use the APIs that might not need authentication.
See also
- Status Codes - how authentication failures surface, e.g. 401 responses for invalid or expired tokens.