Login : Swarm Login API

Important

From Swarm 2022.2, Swarm no longer supports APIs older than v9.

Checking the 2FA authentication

Summary

Checking the 2FA authentication

GET /api/v9/checkauth/

Description

Checking the 2FA authentication

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "results": {
    "trigger": "GAuth says yes!",
    "successMsg": "Second factor authentication approved."
  },
  "code": 200
}

Usage example

Checking the 2FA authentication

To Check User prompt input for 2FA

curl -u "username:password" "https://myswarm.url/api/v9/login/checkauth"

Assuming that the authenticated user has permission, Swarm responds with the next step in the 2FA login:

HTTP/1.1 200 OK

{
  "results": {
    "trigger": "GAuth says yes!",
    "successMsg": "Second factor authentication approved."
  },
  "code": 200
}

Get List of 2FA Methods

Summary

Get List of 2FA Methods

GET /api/v9/listmethods/

Description

Returns the complete list of methods of 2FA.

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "results": {
    "methods": {
      "1": {
        "methodName": "Method Name will be here",
        "methodDesc": "Method Description will be here"
      },
      "2": {
        "methodName": "Method Name will be here",
        "methodDesc": "Method Description will be here"
      },
      "3": {
        "methodName": "Method Name will be here",
        "methodDesc": "Method Description will be here"
      },
      "4": {
        "methodName": "Method Name will be here",
        "methodDesc": "Method Description will be here"
      }
    }
  },
  "option": {
    "persist": "option",
    "nextState": "init-auth"
  },
  "code": 200
}

Usage example

Listing 2FA Methods

To list the 2FA methods:

curl -u "username:password" "https://myswarm.url/api/v9/login/listmethods"

Swarm responds with a list of 2FA methods:

HTTP/1.1 200 OK

{
  "results": {
    "methods": {
      "1": {
        "methodName": "Method Name will be here",
        "methodDesc": "Method Description will be here"
      },
      "2": {
        "methodName": "Method Name will be here",
        "methodDesc": "Method Description will be here"
      },
      "3": {
        "methodName": "Method Name will be here",
        "methodDesc": "Method Description will be here"
      },
      "4": {
        "methodName": "Method Name will be here",
        "methodDesc": "Method Description will be here"
      }
    }
  },
  "option": {
    "persist": "option",
    "nextState": "init-auth"
  },
  "code": 200
}

Get the current effective user details

Summary

Get the current effective user details

GET /api/v9/session

Description

Get user logged in

Example response

Successful Response:

HTTP/1.1 200 OK

{
    "isValid": true,
    "messages": [],
    "user": {
        "User": "reviewer",
        "FullName": "Code Reviewer",
        "Email": "reviewer@swarm.local",
        "Type": "standard",
        "Password": "enabled"
    }
}

Usage example

Getting the currently effective user details

To get session details:

curl -u "<username>:<ticket>" "http://myswarm.url/api/v9/session"

Checking the 2FA authentication

POST /api/v9/checkauth/

Summary

Checking the 2FA authentication

Description

Checking the 2FA authentication

Parameters

Parameter	Description	Type	Parameter Type	Required
token	The token from the user for their 2FA prompt.	string	form	Yes

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "results": {
    "trigger": "otp-generated|||GAuth says yes!",
    "successMsg": "Second factor authentication approved."
  },
  "code": 200
}

Example usage

Checking the 2FA authentication

To Check User prompt input for 2FA

curl -u "username:password" \
     -X POST \
     -d "token=TOKEN" \
     "https://myswarm.url/api/v9/login/checkauth"

Assuming that the authenticated user has permission, Swarm responds with the next step in the 2FA login:

HTTP/1.1 200 OK

{
  "results": {
    "trigger": "GAuth says yes!",
    "successMsg": "Second factor authentication approved."
  },
  "code": 200
}

Initiating the 2FA authentication

Summary

Initiating the 2FA authentication

POST /api/v9/initauth/

Description

Initiating the 2FA authentication

Parameters

Parameter	Description	Type	Parameter Type	Required
method	The Method in which you want to use.	string	form	Yes

Example response

Successful Response:

HTTP/1.1 200 OK

{
  "results": {
     "trigger": "TriggerName",
     "successMsg": "Message from Authentication method"
  },
  "option": {
    "prompt": true,
    "nextState": "check-auth"
  },
  "code": 200
}

Example usage

Initiating the 2FA authentication

To Initiate the user 2FA login:

curl -u "username:password" \
     -X POST 
     -d "method=METHOD" \
     "https://myswarm.url/api/v9/login/initauth"

Assuming that the authenticated user has permission, Swarm responds with the next step in the 2FA login:

HTTP/1.1 200 OK

{
  "results": {
    "trigger": "TriggerName",
    "successMsg": "Message from Authentication method"
  },
  "option": {
    "prompt": true,
    "nextState": "check-auth"
  },
  "code": 200
}

Login to Swarm

Summary

POST /api/v9/login/

Description

Example response

Successful Response:

HTTP/1.1 200 OK

{
     "isValid": true,
     "messages": [],
      "user": {
         "User": "swarm.user",
         "FullName": "Swarm User",
         "Email": "swarm.user@mydomain.com",
         "Type": "standard",
         "Password": "enabled",
         "isAdmin": false,
         "isSuper": false
     }
}

Note

In the event of a failed login attempt Swarm responds with:

Example usage

Logging in to swarm

To login:

curl -H "Content-Type: application/json" \
     -X POST \
     -u "super:<ticket>" \
     -d '{"username":"swarm.user","password":"1234"}' "http://myswarm.url/api/v9/login"

Login to Swarm with SAML

Summary

POST /api/v9/login/saml

Description

Parameters

Parameter	Description	Type	Parameter Type	Required
redirect	Options are: redirect=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. redirect=false: Swarm does not redirect the user.	string	query	No

Parameter

Description

Type

Parameter Type

Required

redirect

Options are:

redirect=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.
redirect=false: Swarm does not redirect the user.

string

query

Example usage

Logging in to swarm with SAML

curl -u "super:<ticket>" \
     -X POST \
     "http://myswarm.url/api/v9/login/saml"

JSON response:

HTTP/1.1 302 OK

{
   "isValid": "true"
   "url": "<url to redirect to>"
}

Logging in to swarm with SAML and redirect=false

curl -u "super:<ticket>" \
     -X POST \
     "http://myswarm.url/api/v9/login/saml?redirect=false"

JSON response:

HTTP/1.1 200 OK

{
   "isValid": "true",
}

Logout of Swarm with optional redirect

Summary

Logout of Swarm with optional redirect

POST /api/v9/logout/

Description

Logout of Swarm

Examples responses

Successful Response:

HTTP/1.1 302 OK

{
     "isValid": true,
     "messages": []
}

Successful Response:

HTTP/1.1 200 OK

{
     "isValid": true,
     "messages": []
}

Note

In the event of a failed login attempt Swarm responds with:

HTTP/1.1 200 OK

{
"isValid": false,
"messages": ["Error message."]
}

Example usage

Logout of Swarm

To logout:

curl -X POST \
     -u "super:<ticket>" \
     "http://myswarm.url/api/v9/logout"

Logout of Swarm without redirect

To logout without any redirect:

curl -X POST \
     -u "super:<ticket>" \
     "http://myswarm.url/api/v9/logout?stay=true"

Create a new Swarm session using the given credentials

Summary

Create a new Swarm session using the given credentials

POST /api/v9/session

Description

Example response

Successful Response:

HTTP/1.1 200 OK

{
    "isValid": true,
    "messages": [],
    "user": {
        "User": "reviewer",
        "FullName": "Code Reviewer",
        "Email": "reviewer@swarm.local",
        "Type": "standard",
        "Password": "enabled"
    }
}

Example usage

Logging in to Swarm

To login:

curl -H "Content-Type: application/json" \
     -X POST \
     -d '{"username": "<username>","password": "<password>","remember": "false"}' \
     -X POST http://localhost/api/v9/session

Destroy the current session, for instance logout

Summary

Destroy the current session, for instance logout

DELETE /api/v9/session

Description

Logout of Swarm

Example response

Successful Response:

HTTP/1.1 200 OK

{
    "isValid": true,
    "messages": []
}

Example usage

Logging out of swarm

To login:

curl -u "<username>:<ticket>" -X DELETE "http://myswarm.url/api/v9/session"