API Auth

Compatibility

• ExpressionEngine 7.3+ (v10). For older versions of ExpressionEngine see the installation page.

Installation

The Auth API comes natively with the Webservice module. The Auth API requires no authentication, so its endpoint is always public.

---

Methods

POST /index.php/webservice/auth — Authenticate

Authenticate a user and retrieve a session ID. Only active members (or roles) that are added in the Webservice module, see Creating members, and Super Admins can authenticate.

---

Request Parameters

Parameter	Type	Required	Description
username	string	Required	Your username or email address
password	string	Required	Your account password
new_session	boolean	Optional	Force creation of a new session: true (or 1, "yes", "on"). false or no value uses the current session

Instead of the username and password, the data can also contain the other credentials: a shortkey, a key and secret or a session_id.

Headers

Header	Value
Content-Type	application/json

---

Request Example

$client = new \GuzzleHttp\Client();

$request = new \GuzzleHttp\Psr7\Request(
    'POST',
    'https://your-domain.com/index.php/webservice/auth',
    ['Content-Type' => 'application/json'],
    json_encode([
        'data' => [
            'username' => 'my-username',
            'password'  => 'your-password',
        ],
    ])
);

$response = $client->send($request, ['timeout' => 2]);

💡 With new_session: Add 'new_session' => true to the data payload to force a new session.

---

Response — 200 OK

{
    "message": "successfully auth",
    "success": true,
    "data": [
        {
            "member_id": 4,
            "session_id": "054b64e828b876b1192170211314a36f58fffb21"
        }
    ]
}

Response Fields

Field	Type	Description
success	boolean	true when authentication succeeded
message	string	Human readable status message
data[].member_id	integer	The authenticated member's ID
data[].session_id	string	Session token to use in subsequent requests, via auth[session_id] or the X-Session-Id header

A session expires after two hours without a call, one hour for a member with access to the control panel (the config overrides website_session_length and cp_session_length change this), and it only works with the same User-Agent as the login. Otherwise the request gets a 401.

Wrong credentials return a 401 with the message cannot auth with given data.

Wrong credentials count as a failed authentication for the rate limiting: after too many from one IP address in a minute, the login gets a 429.

---

POST /index.php/webservice/auth/forgot_password — Forgot password

Available from v10.0.0, before it was part of the Member Tools API

TIP

Forgot password, reset password and resend activation are only available when Member API is on in the API settings.

Sends the Forgotten password instructions email (specialty template) with a reset link, like the forgot password form of ExpressionEngine.

Parameter	Type	Required	Description
email	string	Required	The email address of the member

• The response is the same whether the email address belongs to a member or not, so it cannot be used to find out who is a member.
• A member gets at most 3 reset emails a day, a reset code is valid for one day.
• The link goes to the Password reset URL in the settings, e.g. the reset page of your app: https://app.example.com/reset?token={token}. Without it, the link goes to the reset page of ExpressionEngine.

POST /index.php/webservice/auth/reset_password — Reset password

Available from v10.0.0

Sets a new password with the reset code of the email.

Parameter	Type	Required	Description
resetcode	string	Required	The code of the reset link ({token} or id=)
password	string	Required	The new password, it must match the password rules of ExpressionEngine
password_confirm	string	Required	The new password again

A code can only be used once, the other sessions of the member are ended. A wrong code counts as a failed authentication for the rate limiting.

POST /index.php/webservice/auth/resend_activation — Resend the activation email

Available from v10.0.0, before it was part of the Member Tools API

Sends the activation email again to a member that has not activated the account yet, when Require member account activation is set to email.

Parameter	Type	Required	Description
email	string	Required	The email address of the member

The response is the same whether a pending member exists or not.

Errors

• 403: a banned visitor (forgot_password, resend_activation)
• 422: an invalid email address, a wrong or expired reset code or an invalid password, errors has a message per field
• 429: too many wrong codes, Too many failed attempts, try again later

Hooks

webservice_forgot_password_end, webservice_reset_password_end and webservice_resend_activation_end, with the member_id. forgot_password also calls the member_auth_send_reset_token_start hook of ExpressionEngine.