Login Service: Overview
The Login service provides a REST interface and a set of operations that deal with logging in and out, including getting an authentication token, renewing an authorization token, and deleting an authorization token cookie. This API also includes interfaces to perform SSO login.
For an overview of the tasks managed by this service, and associated tasks, see The Login Process.
URL: https://{hostname}/api/login
| Action | Endpoint | Description |
|---|---|---|
| log in | POST /api/login | Initiates the login process by verifying the credentials of a user who is attempting to log in to the platform. If there are pending login tasks, this operation directs the user to the next task; if there are no pending tasks, it logs the user in, returning an authentication cookie that is used to make authenticated calls to the platform. The cookie is valid for 30 minutes. To renew it, use the POST /api/login/renewToken operation. |
| log out |
use GET /api/login/endsession instead) |
Destroys any authentication cookies associated with the current session for a tenant logging out. Note: We recommend using the GET /api/login/endsession operation, which provides the same functionality, rather than this one which will be deprecated. |
| end session | GET /api/login/endsession | Ends the current session for the user, either on user logout or on session timeout. If user is actively logging out, and had logged in via an external identity provider or remote tenant, this operation also initiates single logout with the external provider or remote tenant. |
| get login domains | GET /api/login/domains | Returns information about the login domains that are valid for the platform. |
| get login status | GET /api/login/status | Returns information about the current user's login status, including whether there is a pending login task that the user must complete as part of the login process. |
| renew token | POST /api/login/renewToken | Updates the time for which an authentication token cookie is valid, as well as other information stored in the cookie. |
| resolve login pending tasks | POST /api/login/pendingtasks | Used if a custom user workflow is in use in the platform that requires custom tasks; for example, entering a two-factor verification code. In this scenario, this operation allows a user to log in, guiding the user through any pending tasks that are needed, including custom tasks, such as 2FA verification, and any standard tasks, such as accepting a legal agreement or changing the password. |
| Operations relating to SSO login: | ||
| SSO login (POST) | POST /api/login/ssoLogin | Logs the user in to an external identity system such as Google or Facebook, for a login domain set up on the platform. |
| SSO login (GET) | GET /api/login/ssoLogin | Allows a user to log in by authenticating with an external identity provider that has its own login screen, providing SSO is enabled between the platform and the identity provider. Examples: Facebook, Google. SSO must already be enabled between the platform and the identity provider; the System Admin must have already created the OpenID Connect domain and enabled it for login. |
| SSO login instructions | GET /api/login/ssoLoginInstructions | Returns applicable instructions for logging in the user, depending on the login option the user has selected. |
| Other: | ||
| app login | POST /api/login/appLogin | Validates the AppID and Shared Secret associated with a specific app. |
| authenticate with password reset code | POST /api/login/authenticateWithPasswordResetCode | Authenticates user with a valid reset code generated with the PasswordManagement API, resets the user's password, and logs the user in. |
| validate registration code | POST /api/login/validateRegistrationCode | Validates the registration code that was issued to a new user as a result of the Site Admin adding the user. |
