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.

Parameters

Parameter Description Type Parameter Type Required

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:

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:

{
  "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
    }
  }
}

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

Summary

Login to Swarm with SAML

POST /api/v11/saml/login

Description

Login to Swarm with SAML.

Parameters

Parameter Description Type Parameter Type Required

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
}