Difference between revisions 482 and 571 on apiportalwiki

<div style="max-width:775px;">
To allow your app to interact with and access content on behalf of a user, use the  [[w:OAuth#OAuth_2.0|OAuth 2.0]] authorization code workflow. 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 includes three steps: [[#2._Request_authorization|request authorization from the user]], [[#3._Get_access_token|get an access token]], and [[#4._Authenticate_request|authenticate the request]].

=== 1. Create app credentials ===

[[Special:UserLogin|Log in]] with your Wikimedia account, and visit [[Special:AppManagement|My clients]]. To create app credentials, select '''Create client''', and choose the '''App credentials''' option. You should have one set of client credentials per app.

=== 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.

<syntaxhighlight lang="bash">
https://meta.wikimedia.org/w/rest.php/oauth2/authorize?client_id={client ID}&response_type=code
</syntaxhighlight>

<div style="background-color: #fef6e7; border: 1px solid; border-color: #fc3; padding: 8px 10px; margin-top:10px;">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. See [[Documentation/Best practices/Security|security best practices]] to learn more.</div>

If the user approves the request, they are redirected to your app’s redirect URI with a query parameter, <code>code</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.

<syntaxhighlight lang="bash">
# Request an access token using an authorization code
curl -X POST -F 'grant_type=authorization_code' \
-F 'code={authorization code}' \
-F 'client_id={client ID}' \
-F 'client_secret={client secret}' \
https://meta.wikimedia.org/w/rest.php/oauth2/access_token
</syntaxhighlight>

The response contains an <code>access_token</code> and a <code>refresh_token</code>.

=== 4. Authenticate request ===

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

<syntaxhighlight lang="bash">
# Get the Earth article from English Wikipedia
curl -H "Authorization: Bearer $AccessToken" \
https://api.wikimedia.org/core/v1/wikipedia/en/page/Earth/bare
</syntaxhighlight>

=== 5. Refresh token ===

Access tokens have limited validity and periodically expire. To get a new access token, submit a POST request using your refresh token, client ID, and client secret.

<syntaxhighlight lang="bash">
# Request an access token
curl -X POST -F 'grant_type=refresh_token' \
-F 'refresh_token={refresh token}' \
-F 'client_id={client ID}' \
-F 'client_secret={client secret}' \
https://meta.wikimedia.org/w/rest.php/oauth2/access_token
</syntaxhighlight>

</div>⏎
__NOTOC__

{{DEFAULTSORT:5}}