Skip to content
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:

  1. 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.
  2. 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 .env file.
  3. 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.
  4. 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.

POST /v1/login
curl -L https://auth.enterprise.wikimedia.com/v1/login -H "Content-Type: application/json" -d '{"username":"yourusername", "password":"secret"}'
200 Response
{
"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.

POST /v1/token-refresh
curl -L https://auth.enterprise.wikimedia.com/v1/token-refresh -H "Content-Type: application/json" -d '{"username":"yourusername", "refresh_token":"your-refresh-token"}'
200 Response
{
"id_token": "string",
"access_token": "string",
"expires_in": 86400
}
Caution:

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

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.

Note:

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.