Skip to content
Wikimedia Enterprise
Documentation menu

Authentication

View as Markdown (opens in a new tab)

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.

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

The Login endpoint returns an ID token, an access token, and a refresh token, with the following expiry:

  • Refresh tokens expire in 90 days.
  • Access and ID tokens expire in 24 hours.
  • Use your Refresh token to obtain a new Access token before it expires.
  • You can get up to 90 new Access tokens with the same Refresh token. Once you go over that limit, use the Login endpoint to generate a new Refresh token.

Store your access_token and refresh_token in a safe place, like a .env file or other local dotfile. Don't use the Login endpoint every 24 hours to get a new access_token; call Refresh Token instead, so that ideally you use Login only once every 90 days. The refresh response carries a new access_token and id_token with expires_in, and no new refresh_token: keep using the one from login, for up to 90 refreshes or 90 days, whichever comes first. If a refresh token should stop working, call Revoke Token to revoke the access tokens generated by that refresh token.

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
}
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 are a Wikimedia community member, you can get exclusive access to Wikimedia Enterprise APIs that might not need authentication. Request community access on Meta.

See also

  • Status Codes - how authentication failures surface, e.g. 401 responses for invalid or expired tokens.