Authentication

🚧  Work in progress
This page is a draft. The information on this page is currently in development.

Apps using the Wikimedia API should authenticate their requests using OAuth 2.0. This provides a secure process for accessing Wikimedia resources and applies an app-specific rate limit. For a streamlined experience for evaluation and prototyping, you can authenticate using a personal API token.

• App authentication: OAuth 2.0 client credentials flow
• User authentication: OAuth 2.0 authorization code flow
• Personal API token
• Troubleshooting

App authentication

To authenticate a request on behalf of an app, use the OAuth 2.0 client credentials flow. This flow lets you access public Wikimedia content like Wikipedia articles using a client ID and client secret.

The OAuth 2.0 client credentials flow is not supported for client-side or installed apps (mobile, desktop, and single-page apps). Instead, use the user authentication flow. Read security best practices to learn more.

1. Create credentials

Log in with your Wikimedia account, and visit the API keys dashboard. To create credentials, select Create key, and choose the server-side app option. After creating the key, you'll be shown a client ID and secret. Make sure to store these credentials securely before exiting the dialog.

2. Get an access token

To start the authentication process, use your client credentials to request an access token from the authentication server. The Wikimedia API uses meta.wikimedia.org as the authentication server. To request an access token, submit a POST request using your client ID and secret.

# Request an access token using a client ID and secret
curl -X POST -d 'grant_type=client_credentials' \
-d 'client_id=YOUR_CLIENT_ID' \
-d 'client_secret=YOUR_CLIENT_SECRET' \
https://meta.wikimedia.org/w/rest.php/oauth2/access_token

The response contains an access_token.

3. Authenticate your request

To authenticate an API request, include the access token in the Authorization request header using the Bearer authentication scheme.

# Get the Earth article from English Wikipedia
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.wikimedia.org/core/v1/wikipedia/en/page/Earth/bare

4. Refresh the access token

Access tokens have limited validity and expire after four hours. To get a new access token, re-submit the POST request in step 2.

User authentication

To allow your app to interact with and access content on behalf of a user, use the OAuth 2.0 authorization code flow. This provides a secure process for users to log in with their Wikimedia account and authorize your app. The OAuth 2.0 authorization code workflow can be used by server-side, client-side, and installed apps.

The OAuth 2.0 authorization code workflow includes three steps: request authorization from the user, get an access token, and authenticate the request.

1. Create credentials

Log in with your Wikimedia account, and visit API keys dashboard. To create credentials, select Create key, and choose your app type. You should have one set of credentials per app.

Choosing a redirect URI

To use the authorization code flow, you'll need to choose a redirect URI for your app. Following successful authorization, the authorization server redirects users to your app via this path. Learn more about redirect URLs for mobile apps.

2. Request authorization

The first step in the workflow is to exchange user approval for an authorization code. To request authorization, ask your users to click on a link containing the Wikimedia API authentication server URL, client ID, and response type. This takes them to a page on meta.wikimedia.org where they can log in with their Wikimedia account and approve the request.

https://meta.wikimedia.org/w/rest.php/oauth2/authorize?client_id=YOUR_CLIENT_ID&response_type=code

For mobile apps, desktop apps, Javascript apps, or other types of apps that publish client secrets in user-accessible code, include a PKCE code challenge in your authorization request. Read security best practices to learn more.

If the user approves the request, they are redirected to your app’s redirect URI with a query parameter, code, that contains the authorization code. You can use this code to get an access token.

3. Get access token

Now that you have an authentication code, you can use it to get an access token from the authentication server. To request an access token, submit a POST request using your authorization code, client ID, and client secret.

# Request an access token using an authorization code
curl -X POST -d 'grant_type=authorization_code' \
-d 'code=YOUR_AUTHORIZATION_CODE' \
-d 'client_id=YOUR_CLIENT_ID' \
-d 'client_secret=YOUR_CLIENT_SECRET' \
https://meta.wikimedia.org/w/rest.php/oauth2/access_token

The response contains an access_token and a refresh_token.

4. Authenticate request

To authenticate an API request, include the access token in the Authorization request header using the Bearer authentication scheme.

# Get the Earth article from English Wikipedia
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.wikimedia.org/core/v1/wikipedia/en/page/Earth/bare

5. Refresh token

Access tokens have limited validity and expire after four hours. To get a new access token, submit a POST request using your refresh token, client ID, and client secret. Refresh tokens are valid for 365 days.

# Request an access token using a refresh token
curl -X POST -d 'grant_type=refresh_token' \
-d 'refresh_token=YOUR_REFRESH_TOKEN' \
-d 'client_id=OUR_CLIENT_ID' \
-d 'client_secret=YOUR_CLIENT_SECRET' \
https://meta.wikimedia.org/w/rest.php/oauth2/access_token

Personal API tokens

Personal API tokens let you authenticate API requests on behalf of your Wikimedia account. You can use personal API tokens for testing and evaluation, running scripts locally, and prototyping apps.

Personal API tokens are tied to the account that created them and must be stored securely. Do not share or publish your personal API token.

1. Create token

Log in with your Wikimedia account, and visit My clients. To create an API token, select Create client, and select the Personal API token option. Remember to store your access token in a secure place, like a password manager.

2. Authenticate request

To authenticate an API request, include your access token in the Authorization request header using the Bearer authentication scheme. Personal access tokens are valid indefinitely and do not expire.

# Get the Earth article from English Wikipedia
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://api.wikimedia.org/core/v1/wikipedia/en/page/Earth/bare

Troubleshooting

Request fails with a rest-read-denied error

This error can happen when a project doesn't recognize new API Portal accounts. If you encounter this error, try visiting the project you're trying to access and logging in with your API Portal account.