--- title: "Service: /authenticate [POST]" source: https://dev.pageseeder.com/api/services/authenticate_post.html description: "The /authenticate [POST] service handles user authentication in PageSeeder through login, logout, and code request actions, supporting multiple sign-in methods including password, authentication codes, and ID tokens for Single Sign-On integration." last_updated: 2026-09-08T14:06:35+10:00 document_type: api_endpoint operation_id: member-POST resource_id: member path_template: /authenticate http_method: POST api_category: member implementation_version: 6.2000 api_since: 6.0000 deprecated_since: null obsolete_since: null api_support: experimental cache_control: N/A generated_at: 2025-08-04 tokens: ~2944 --- # /authenticate \[POST\] ## Description Handles user authentication by creating and terminating users session. The action parameter and sign-in method determines the authentication process. | Action | Process | | --- | --- | | `login` | Sign in to PageSeeder (with [password](../../reference/glossary/password.md), [authentication code](../../reference/glossary/authorization_code.md) or [ID token](../../reference/glossary/id_token.md)) by authenticating a member and creating a session. | | `logout` | Sign out of PageSeeder by terminating the user session. | | `code` | Request an authentication code to sign in with code. | Use this service to implement [Single Sign-On (SSO)](../../reference/glossary/single_sign-on.md). > **Note:** All authentication events, whether they are successful or not, are recorded in the [access logs](../../reference/folders_and_files/state_folder/logs.md). The session timeout is configurable with the `sessionTimeout` [global property](../../guide/configuration/properties/global_properties.md). > **Warning:** If your app does not require a session, you do not need to use this service. Use access tokens instead with OAuth authorization code flow. ### Sign in with password This sign-in method lets the user sign in using their username or email address, and their password. This is the default method and is available to all users unless their email domain is flagged as external only in the identity configuration. The “remember me” option, sets a encrypted cookie on the client so that the user does not have to sign in again. Signing out destroys the cookie and requires the user to sign in again. > **Warning:** The account is [locked](../../reference/glossary/account_lockout.md) when there are multiple consecutive failed sign-in attempts. > **Tip:** For the same reasons that [OAuth 2.0 Security Best Current Practice](https://tools.ietf.org/html/draft-ietf-oauth-security-topics-13#section-3.4) disallows the password grant entirely, we don’t recommend that you let your users enter their credentials outside PageSeeder as it is considered bad practice. The only case where it is acceptable is when users are never exposed to PageSeeder and only manage their credentials through your app. ### Sign in with code This sign-in method lets a trusted third-party app sign in on behalf of the user using an *authentication code*. This code is a One-Time-Password (OTP) and can only be acquired using the `code` action using this service. This method is only available to users who have an email address and the email domain is listed in the identity configuration. ### Sign in with token This sign-in method lets a trusted third-party app sign in the user directly using an *ID token* issued by a registered external identity provider. This method is only available to users who have an email address and the email domain is listed in the identity configuration. ### Sign out The `logout` action is always successful regardless of whether the user is authenticated or not. If the user is authenticated: - The session is invalidated and destroyed. - The “remember me” cookie is deleted. ### Code request Use this action to acquire a single use authentication code to use as part of a Single Sign On (SSO) authentication flow. To get an authentication code, the following conditions must be met: - A valid ID token is provided using the id\_token parameter. - The `iss` and `aud` claims in the ID match an external ID provider in the external identity config. - The domain of `email` address from the ID token matches an authorised email domain in the external identity config. - A registered client ID is provided using the client\_id parameter. - The `email` in the ID token matches an existing user account. When successful, a one-time-use authorization code is returned in the response and can be used for sign in with `action=login`. > **Tip:** During the code request, the client app exchanges an ID token for an authentication code. The authentication code is then used by the browser to receive the Cookie containing the PageSeeder session ID.  ## Parameters The set of parameters to use depends on the action parameter and sign-in method used. ### Sign in with password | Name | Description | Required | Type | Default | | --- | --- | --- | --- | --- | | action | Set to `login` | yes | string | | | login-username | The username or email of the user  | yes | string | | | login-password | The password of the user | yes | string | | | remember | Whether to remember this sign in | no | boolean | `false` | Both the username and password are limited to 100 characters. ### Multi-factor authentication After sign in with password, if the user has previously [registered an MFA authenticator](authenticators-self_post.md) the response will contain a list of their authenticators and a challenge for the most recently used authenticator. Then the user must verify that challenge or request a new challenge using the following parameters. *Requires PageSeeder v6.2 or later.* | Name | Description | Required | Type | Default | | --- | --- | --- | --- | --- | | action | Set to `challenge`  | yes | string | | | authenticator | The authenticator public ID | yes | string | | | challenge | The ID of the challenge to be verified (if not specified and 1 minute has passed a new challenge is created) | no | string | | | code | The authentication code for verification (required if `challenge` param and no `credential` param) | maybe | string | | | credential | The challenge response for verification (required if `challenge` param and no `code` param) | maybe | string | | ### Sign in with code | Name | Description | Required | Type | Default | | --- | --- | --- | --- | --- | | action | Set to `login` | yes | string | | | client\_id | The client ID | yes | string | | | auth\_code | The authentication code to sign in | yes | string | | ### Sign in with token | Name | Description | Required | Type | Default | | --- | --- | --- | --- | --- | | action | Set to `login` | yes | string | | | id\_token | The ID token to sign in | yes | string | | ### Sign out | Name | Description | Required | Type | Default | | --- | --- | --- | --- | --- | | action | Set to `logout` | yes | string | | > **Note:** No other parameter is required, but the service uses the session cookie to determine which session to terminate. If the cookie isn't included in the request, this action has no effect. ### Code request | Name | Description | Required | Type | Default | | --- | --- | --- | --- | --- | | action | Set to `code` | yes | string | | | client\_id | The client ID | yes | string | | | id\_token | The ID token to sign in | yes | string | | | scope | Scope for authentication code | no | string | "" | > **Tip:** During the code request, the client app effectively exchanges an ID token for an authentication code. ## Permission This is a public service: anyone can use this service. This service supports [CORS](../../reference/glossary/cors.md). ## Response The XML response returned is as follows, where `` and `` elements are only included for `status="challenge"`: ```xml  []  [           ] ``` The following is a summary of the response statuses based on the action and sign-in method. | Action | Sign-method | Condition | Status | | --- | --- | --- | --- | | `login` | Password | User account is locked | `locked` | | `login` | Password | User account requires activation | `activation_required` | | `login` | Password | Email domain configured as external only | `external_only` | | `login` | Password | Credentials are correct and an MFA authenticator registered for user | `challenge` | | `login` | Any | Credentials are correct and no error | `success` | | `challenge` | MFA | Authenticator ID is valid | `challenge` | | `challenge` | MFA | Challenge ID and code/credentials are valid | `success` | | `challenge` | MFA | Authenticator is locked | `locked` | | `code` | Token | Credentials are correct and no error | `auth_code` | | `logout` | Any | Any | `logout` | | Any | Any | Credentials are incorrect or any other error | `failed` | ### Successful sign-in When the action parameter is `login`, the sign-in is successful. The sign-in method does not affect the response and returns: ```xml ``` or ```json { "status": "success" } ``` This response also includes the session Cookie. ### Locked account When the action parameter is `login`and the sign-in method is password but the account is locked due to repeated sign-in failures, this service responds with: ```xml ``` or ```json { "status": "locked" } ``` > **Note:** For security reasons, this service does not indicate how long an account is locked for or how many unsuccessful sign-ins caused the account to be locked. Administrators can unlock a user account from the **Account profile** page of the user in the system administration. ### Unactivated account When the action parameter is `login` and the sign-in method is password but the account has not been activated by the user, this service responds with the status `activation_required` and includes the email address of the user to be used for [account activation](../../reference/glossary/account_activation.md). This is to let the user or client app know that the user must activate their account and occurs even if the submitted user credentials are valid. For example: ```xml ``` or ```json { "status": "activation_required", "email":"somebody@example.org" } ``` ### External only When the action parameter is `login`and the sign-in method is password but the domain of the email address used for sign-in is configured to be external only in the identity config, this service responds with the status `external_only`. This is to let the user or client app know that the user cannot sign-in directly via PageSeeder and occurs even if the submitted user credentials are valid. For example: ```xml ``` or ```json { "status": "external_only" } ``` ### Sign out When the action parameter is `logout`, the response is always: ```xml ``` or ```json { "status": "logout" } ``` ### Code When the action parameter is `code` and the response is successful: ```xml ``` or  ```json { "status": "auth_code", "code": "[one-time-auth-code]" } ``` > **Warning:** Authentication codes are credentials and must be protected adequately. ## Error handling | HTTP status code | Error condition | | --- | --- | | **400** | The specified action parameter is invalid. | For security reasons, this service does not disclose the reason for failure. It returns the following response with HTTP 200 status code: ```xml ``` Or if JSON was requested: ```json { "status": "failed" } ```