# 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](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/login) endpoint to receive your tokens, then use the [Refresh Token](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/token-refresh) and [Revoke Token](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/token-revoke) 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](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/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](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/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](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/login) endpoint every 24 hours to get a new `access_token`; call [Refresh Token](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/token-refresh) 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](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/token-revoke) 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](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/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. ```bash title="POST /v1/login" curl -L https://auth.enterprise.wikimedia.com/v1/login -H "Content-Type: application/json" -d '{"username":"yourusername", "password":"secret"}' ``` ```json title="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 - [`/v1/login`](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/login) - Receive auth tokens by providing a username and password (POST) - [`/v1/token-refresh`](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/token-refresh) - Receive auth tokens by providing a refresh token (POST) - [`/v1/token-revoke`](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/token-revoke) - Revoke all access tokens generated by a refresh token (POST) - [`/v1/forgot-password`](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/forgot-password) - Start the forgot-password flow for a given user (POST) - [`/v1/forgot-password-confirm`](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/forgot-password-confirm) - Change a user password as part of the forgot-password flow (POST) - [`/v1/change-password`](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/change-password) - Replace an old user password with a new password (POST) - [`/v1/new-password-required`](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/new-password-required) - Respond to a new-password-required challenge (POST) [Forgot Password](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/forgot-password) sends a confirmation code by email. Use that code as input for the [Forgot Password Confirmation](https://enterprise.wikimedia.com/docs/api/#tag/authentication/POST/v1/forgot-password-confirm) 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](https://meta.wikimedia.org/wiki/Wikimedia_Enterprise#Access). ## See also - [Status Codes](https://enterprise.wikimedia.com/docs/status-codes/) - how authentication failures surface, e.g. 401 responses for invalid or expired tokens.