The Login Controller manages user authentication and session management, implementing various login mechanisms including traditional password-based authentication, Multi-Factor Authentication (MFA), and Single Sign-On (SSO).
Reference
Login
This endpoint handles user authentication through multiple methods. It validates credentials, enforces password policies, manages MFA requirements, and initiates SSO flows when needed. Upon successful authentication, it issues cookies and directs users to the authorization flow.
| Field | Type | Required | Description |
|---|---|---|---|
| client_id | string | ✗ | client_id for the login |
| code_challenge | string | ✗ | Forwarded code_challenge for PKCE support |
| code_challenge_method | string | ✗ | Forwarded code_challenge_method for PKCE support allowed values: S256 |
| debug | boolean | ✗ | If true, no redirect but an answer is given |
| device | string | ✗ | device for the login. Prefer sending as x-admiralcloud-device header. |
| ✓ | E-Mail that wants to login | ||
| env | string | ✗ | env for the login |
| iframe | integer | ✗ | env for the login allowed values: 12 |
| loginCookie | boolean | ✗ | If true, a cookie is set during login to keep the user logged in |
| mfaCode | string | ✗ | mfaCode for the login |
| mfaPassword | string | ✗ | mfaPassword for the login |
| password | string | ✗ | Password for the login |
| redirect_uri | string | ✗ | redirect_uri for Oauth2 login. Do not use trailing slashes or query parameters. |
| resource | string | ✗ | Resource to request access to – structure TYPE:MEDIACONTAINER_ID |
| response_type | string | ✗ | response_type for the login allowed values: codecookie |
| state | string | ✗ | Recommended state parameter for the login to avoid CSRF attacks (RFC 6749). If not set, a short term cookie is set for authentication. |
| token | string | ✗ | Reset token for the login |
| Field | Type | Description |
|---|---|---|
| authorization | object | Authorization Object |
| code | string | Code that needs to be exchanged for token |
| code_challenge | string | Forwarded code_challenge for PKCE support |
| code_challenge_method | string | Forwarded code_challenge_method for PKCE support allowed values: S256 |
| cookie | string | |
| customer | object | customer object |
| └ id | integer | id of the customer |
| mfaCode | string | MFA Code |
| name | string | YXXt |
| state | string | Recommended state parameter for the login to avoid CSRF attacks (RFC 6749). If not set, a short term cookie is set for authentication. |
| url | string | YXXt |
| user | object | User object |
| └ customerId | integer | Customer id for this session |
| └ id | integer | Id of the user |
| └ adminLevel | integer | The user`s admin level in this session |
| email address of the user | ||
| └ cookieIdentifier | string | TBA |
Logout
The logout endpoint supports different scope parameters to control the extent of session termination.
Scope Parameters
Global Logout
- Parameter:
scope=global - Effect: Terminates all active sessions across all applications and devices
- Cookie Handling: Login cookie is destroyed
- Use Case: Complete user logout from all services
App Logout
- Parameter:
scope=app - Effect: Terminates all sessions for the specified application only
- Cookie Handling: Login cookie is preserved but user needs to login again for this app
- Use Case: User wants to logout from a specific application while maintaining access to other applications
Device Logout
- Parameter:
scope=device - Effect: Terminates all sessions for the specified device across all applications
- Cookie Handling: Login cookie is preserved, but user needs to login again for this app
- Use Case: User wants to logout from a specific device/browser while maintaining sessions on other devices
Session Logout
- Parameter: no scope parameter
- Effect: Terminates only the current session (specific client + device combination)
- Cookie Handling: Login cookie is preserved
- Use Case: Standard logout from current application and device only
Cookie Management Rationale
The login cookie represents user authentication (identity verification), while sessions represent authorization (access permissions for specific applications and devices).
Only global logout destroys the authentication cookie, as this represents a complete logout from all services. Partial logouts maintain the authentication state to allow seamless access to other authorized applications and devices.
But, if you logout an app you cannot acquire a new session, even though the cookie is still valid. In this case, our Authentication server will require you to login again.
| Field | Type | Required | Description |
|---|---|---|---|
| redirect_uri | string | ✗ | redirect_uri for Oauth2 login. Do not use trailing slashes or query parameters. |
| scope | string | ✗ | Scope of the logout allowed values: appdeviceglobal |
| Field | Type | Description |
|---|---|---|
| cookie | string | |
| logout | boolean | True if logout was successful. |
| scope | string | Scope of the logout allowed values: appdeviceglobal |
Reset Password
This endpoint facilitates password reset and user invitation processes, generating secure reset tokens and managing email notifications.
| Field | Type | Required | Description |
|---|---|---|---|
| client_id | string | ✓ | client_id for the login |
| ✓ | E-Mail that wants to login | ||
| env | string | ✗ | env for the login |
| forceInvite | boolean | ✗ | Force invite even if user has logged in before |
| operation | string | ✗ | operation can be invite or resetpassword allowed values: inviteresetpassword |
| redirect_uri | string | ✗ | redirect_uri for Oauth2 login. Do not use trailing slashes or query parameters. |
| Field | Type | Description |
|---|---|---|
| E-Mail that wants to login | ||
| operation | string | operation can be invite or resetpassword allowed values: inviteresetpassword |
| requestInviteLink | string | Invitaton link |
| token | string | Reset token for the login |
Check Password
This endpoint evaluates password strength against security requirements.
| Field | Type | Required | Description |
|---|---|---|---|
| ✓ | E-Mail that wants to login | ||
| password | string | ✓ | Password for the login |
| Field | Type | Description |
|---|---|---|
| check | object | Object with information why your password is not safe |
| statusCode | integer | Status code of the operation |
Login with MFA
Use this endpoint to login with MFA
| Field | Type | Required | Description |
|---|---|---|---|
| client_id | string | ✓ | client_id for the login |
| code_challenge | string | ✗ | Forwarded code_challenge for PKCE support |
| code_challenge_method | string | ✗ | Forwarded code_challenge_method for PKCE support allowed values: S256 |
| device | string | ✗ | device for the login. Prefer sending as x-admiralcloud-device header. |
| mfaToken | string | ✓ | OTP for the login |
| redirect_uri | string | ✓ | redirect_uri for Oauth2 login. Do not use trailing slashes or query parameters. |
| resource | string | ✗ | Resource to request access to – structure TYPE:MEDIACONTAINER_ID |
| state | string | ✗ | Recommended state parameter for the login to avoid CSRF attacks (RFC 6749). If not set, a short term cookie is set for authentication. |
Deactivate MFA
This endpoint deactivates/resets MFA for a given user.
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | ✓ | Deactivates MFA for the given user |
| Field | Type | Description |
|---|---|---|
| id | integer | Deactivates MFA for the given user |
| mfakey | string | The response will contain null for this value to indicate that MFA is deactivated/reset |
Mark trusted
This endpoint manages trust status for login sessions, allowing users to mark devices as trusted or untrusted, affecting future authentication requirements.
| Field | Type | Required | Description |
|---|---|---|---|
| loginuid | string | ✓ | Login UID |
| trusted | integer | ✓ | Value of trust allowed values: 59 |
Login as app
Login as app, e.g. for mediahubs
| Field | Type | Required | Description |
|---|---|---|---|
| additionalParams | object | ✗ | Optional parameters that can be passed to customize the authentication flow. Contact our team for details. |
| client_id | string | ✗ | OAuth client identifier – required for application authentication |
| debug | boolean | ✗ | When set to true, provides verbose logging for troubleshooting integration issues |
| ✓ | Email address of the user to authenticate | ||
| firstname | string | ✓ | First name of the user for account identification and personalization |
| lastname | string | ✓ | Last name of the user for account identification and personalization |
| settings | object | ✗ | Please do not use without anymore |
| state | string | ✗ | Unique identifier for the authentication session that must be used in subsequent code requests |