Login: Swarm login

Get Swarm user session details

Summary

Get Swarm session details of a user.

GET /api/v11/session

Description

Get the Swarm session details of a user.

Example usage

Get the session details for bruno:

curl -u "bruno:<ticket>" https://my-swarm-host/api/v11/session

Swarm responds with:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [{
    "code": "user-login-successful",
    "text": "User logged in."
  }],
  "data" : {
    "user": {
      "User": "bruno",
      "Type": "standard",
      "Email": "bruno@swarm.local",
      "FullName": "bruno",
      "isAdmin": true,
      "isSuper": false
    }
  }
}

If a request fails

<error code>:

  • 401 Incorrect or missing credentials

  • 403 Unauthorized

HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Create a new Swarm user session

Summary

Create a new Swarm user session.

POST /api/v11/session

Description

Create a new Swarm user session.

When creating a new Swarm user session with a valid sso user, you must call Get SSO authentication URL API endpoint to get the navigation URL. This navigation URL must be opened in a web browser to login the user. Once the user is logged in, a login successful message for this user is displayed in the Create a new Swarm user session API endpoint.

Parameters

Parameter Description Type Parameter Type Required

method

Login service type identifier. The default value is basic.

  • basic: uses basic authentication to login to Swarm

  • sso: uses sso configurable as follows:

    • enabled all users must use Helix Authentication Service to log in to Swarm.

      The login page displays an input box to enter the email or username. Once the input box is filled, the Log in with SSO button is activated. See Log in with SSO.

      If SAML is configured when the sso configurable is enabled, the user can only log in to Swarm using the Log in with SSO button.

    • optional Helix Authentication Service is available for users to log in to Swarm but is not enforced.

      The login page displays an input box to enter the email or username. Once the input box is filled, the Log in with SSO button is enabled. To log in with SSO, see Log in with SSO.

      The user can also manually log in to Swarm using the Log in with credentials button. To log in manually, see Log in with a password.

      If you switch to Log in with credentials and then decide to use single sign-on, click Log in with SSO.

      If SAML is configured when the sso configurable is set to optional, the user can either log in to Swarm using the Log in with SSO button or the Log in with credentials button.

    • disabled Helix Authentication Service is not available to Swarm. This is the default value.

      The login page displays two input boxes to enter the email or username, and to enter the password. Once the input boxes are filled, the Log in with credentials button is activated. See Log in with a password.

string

body

No

username

Username

string

body

Yes

password

User ticket (recommended) or password

Important

If your Helix Core Server is set to security level 3 or higher, you must use a ticket value for the password parameter.

string

body

Yes

remember

  • true: User stays logged in between browser restarts.

  • false: User does not stay logged in between browser restarts. This is the default if the remember parameter is not in the body or if it does not have a value.

Boolean

body

No

Example usage

Create a new Swarm session for bruno using the basic method

curl -X POST -H "Content-Type: application/json" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/session"

The "mybodyfilename.txt" file contains the login details for bruno:

{
  "method":"basic",
  "username": "bruno",
  "password": "A1AFB97F0F218DF7B122F229C7DECA46",
  "remember": false  
}

Swarm responds with:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [
    {
      "code": "user-login-successful",
      "text": "User logged in."
    }
  ],
  "data" : {
    "user": {
      "User": "bruno",
      "Type": "standard",
      "Email": "bruno@swarm.local",
      "FullName": "bruno",
      "isAdmin": true,
      "isSuper": false
    }
  }
}

Create a new Swarm session for bruno using the sso method:

curl -X POST -H "Content-Type: application/json" -d "@mybodyfilename.txt" "https://my-swarm-host/api/v11/session"

The "mybodyfilename.txt" file contains the login details for bruno:

{
  "method":"sso",
  "username": "bruno",
  "remember": false  
}

Swarm responds with:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [
    {
      "code": "user-login-successful",
      "text": "User logged in."
    }
  ],
  "data" : {
    "user": {
      "User": "bruno",
      "Type": "standard",
      "Email": "bruno@swarm.local",
      "FullName": "bruno",
      "isAdmin": true,
      "isSuper": false
    }
  }
}

If a request fails

<error code>:

  • 401 Incorrect or missing credentials

  • 403 Unauthorized

HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Get SSO authentication URL

Summary

Get Swarm SSO authentication URL.

GET /api/v11/get-sso-auth-url

Description

Get Swarm SSO authentication URL.

Example usage

Get Swarm SSO authentication URL for bruno.

curl -u "bruno:<ticket>" https://my-swarm-host/api/v11/get-sso-auth-url

Swarm responds with:

HTTP/1.1 200 OK		

{
  "data": {
    "url": "https://10.153.120.29:3000/oidc/login/01HR6QMK0MPC5J506C2WG5ZZ0R?instanceId=none",
    "isValid": true,
    "errors": null
  },
  "messages": null,
  "error": null
}

If a request fails

<error code>:

  • 401 Incorrect or missing credentials

  • 403 Unauthorized

HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Login to Swarm with SAML

Important

Swarm now supports Helix Authentication Service (HAS) as a Single Sign-On (SSO) provider. This helps to simplify configuration and create a more robust SSO solution. The SAML configuration will be removed from Swarm in a later release.

If SAML is configured when the sso configurable is set to optional, the user can either log in to Swarm using the Log in with SSO button or the Log in with credentials button. If SAML is configured when the sso configurable is enabled, the user can only log in to Swarm using the Log in with SSO button.

Summary

Login to Swarm with SAML

POST /api/v11/saml/login

Description

Login to Swarm with SAML.

Parameters

Parameter Description Type Parameter Type Required

method

Login service type identifier is set to use saml configuration to login to Swarm.

string

body

No

redirect

Options are:

  • true or not specified: Swarm redirects the user to the HTTP_REFERER url or to the specified custom logout_url if it has been set.
  • false: Swarm does not redirect the user.

string

query

No

Example usage

Login in to Swarm with SAML

Login in to Swarm with SAML.

curl -X POST -u "super:<ticket>" "https://myswarm-url/api/v11/saml/login"

On successful login Swarm responds with:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "isValid": "true",
    "url": "<url to redirect to>"
  }
}

Login in to Swarm with SAML and redirect=false

Login in to Swarm with SAML and redirect=false

curl -X POST -u "super:<ticket>" "https://myswarm-url/api/v11/saml/login?redirect=false"

On successful login Swarm responds with:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [],
  "data" : {
    "isValid": "true"
  }
}

If a request fails

<error code>:

    400 Error occurred with the SAML login

HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
} 

Logout of a Swarm user session

Summary

Logout of a Swarm user session.

DELETE /api/v11/session

Description

Logout of a Swarm user session.

Example usage

Logout bruno of a Swarm user session.

curl -X DELETE -u "bruno:<ticket>" https://my-swarm-host/api/v11/session

Swarm responds with:

HTTP/1.1 200 OK		

{
  "error": null,
  "messages": [
    {
      "code": "user-logged-out",
      "text": "Successful Logout."
    }
  ],
  "data": {
    "url": "/"
  }
}

If a request fails

<error code>:

  • 401 Incorrect or missing credentials

  • 403 Unauthorized

HTTP/1.1 <response error code>		

{
  "error": <error code>,
  "messages": [{
    "code" : "<code string>",
    "text" : "<error message>"
  }],
  "data" : null
}