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.

When a new user is logging in for the first time, depending on platform configuration, there might be tasks that the user must complete. The login operation checks whether any of those tasks are pending. If there are one or more pending tasks, the response specifies the next task to be completed. When all tasks are complete, login is complete. Pending tasks are prioritized as follows:

1. Changing the password (this requirement can be specified by the Site Admin when adding a user by invoking the POST /api/users operation). To complete this task using the API, invoke the PUT /api/users/{UserID}/password operation.
2. Accepting the platform legal agreement. To complete this task using the API, invoke the POST /api/legals/agreements operation.
3. Providing answers to security challenge questions. To complete this task using the API, invoke the PUT /api/users/{UserID}/challenges operation.

Note: In versions prior to 8.0, this operation returned the AtmoAuthToken in the response. From 8.0 onwards it returns the token in the Set-Cookie header.

Authorization Roles/Permissions: To complete this operation successfully, a user must be registered on the platform or be in process of registering.

This topic includes the following sections:

HTTP Method

POST

URL

https://{hostname}/api/login

Sample Request

The example below sends the username and password for authentication of the user logging in.

Sample request URL

https://{hostname}/api/login

Sample request headers

POST /api/login HTTP/1.1
Host:{hostname}
Accept: application/json, text/javascript, */*; q=0.01
Content-Type: application/json; charset=UTF-8

Sample request body

{
  "email":"myemailaddress@myemail.com",
  "password":"Mypwd_12345"
}

Sample request: Curl

curl -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -i 'https://{hostname}/api/login' --data '{
  "email":"administrator@acmepaymentscorp",
  "password":"Pa$sW0rd_12345",
  "federationLogins":true
}'

Request Headers

For general information on request header values, refer to HTTP Request Headers.

Header	Description
Accept	application/json, application/vnd.soa.v71+json, application/vnd.soa.v72+json, application/vnd.soa.v80+json, application/vnd.soa.v81+json
Content-Type	Any one of the following media types is valid for the request Content-Type: application/json, application/vnd.soa.v71+json, application/vnd.soa.v72+json, application/vnd.soa.v80+json, application/vnd.soa.v81+json

Request Parameters

Parameter	Parm Type	Data Type	Required	Description
LoginRequest	Body	LoginRequest	Required	Email and password for the user logging in. Both values are required.

Response

If successful, this operation returns HTTP status code 200, with an updated cookie for the user in JSON format.

Sample Response

The sample response below shows the user logging in. The cookie is returned in the Set-Cookie header. This example also includes the X-Csrf-Token_{fedmemberID} header, which may or may not be returned, based on platform settings. For more information, see Cookies in the Akana API Platform and CSRF Prevention on the Platform.

Sample response headers

HTTP/1.1 200 OK
Content-Type: application/json
Expires: Mon, 27 Jul 2015 12:36:55 GMT
Set-Cookie: AtmoAuthToken_acmepaymentscorp=TokenID%3D13544611-3486-11e5-9f5c-cb8d33c7f3c7%2Cclaimed_id%3Durn%3Aacmepaymentscorp%3Auser%3Aacmepaymentscorp%3A5a48b51d-b726-460f-bec5-8fb4e392137c%2CissueTime%3D1438018615951%2CexpirationTime%3D1438020415922%2CAttributesIncluded%3Dfalse%2CUserFDN%3D5a48b51d-b726-460f-bec5-8fb4e392137c%252Eacmepaymentscorp%2CUserName%3Dadminacmepaymentscorp%2Csig%3DcoY4laDvxkQ4vLLg6Tkfc9X35THApqFPh3hONnbCwXsNNjaKxUu9Ce98jf88kPEcrImd69Ry2N8XIrzICKTaUdCIni2ETKNCccpbYfBWftTQoUNVpQffzUTCP965GKqPLf6Zo0ol48TCRn4bWepqz8pycFczAhlsrl-WQBq0Adg;path=/;expires=Mon, 27 Jul 2015 18:01:55 GMT;HttpOnly
Csrf-Token_acmepaymentscorp=TokenID%3D13544611-3486-11e5-9f5c-cb8d33c7f3c7%2CexpirationTime%3D1438020415969%2CUserFDN%3D5a48b51d-b726-460f-bec5-8fb4e392137c%252Eacmepaymentscorp%2Csig%3DMKd7acZkLzsMIalD2LFhmuLPy58xa-NlxoWucWi3WVfO8UTsz_t88fCjQIQHKH-pRol_1wsGVHRnz3riAl7eKrRYEo68XOMn1UnoMYXQUX9mTGtGoTXgu61Dk7vIIiVhBJV1AIRZiHKoDim04hq-tjw8NIeHdH6DV7M2COAaTZA;path=/;expires=Mon, 27-Jul-2015 18:01:55 GMT

Sample response body #1

In the example below, the Site Admin added the user (using the POST /api/users operation) and the user is now logging in for the first time. The Site Admin specified that the user must change password on first login (ForcePasswordChangeOnLogin parameter in the Add User operation); therefore, change password is listed as a pending task. Tokens have been abbreviated.

To change the password, invoke the PUT /api/users/{UserID}/password operation.

{
    "userFDN": "3d764293-d647-4bfb-8d8b-f82b98457021.acmepaymentscorp",
    "userName": "JaneMead",
    "status": "success",
    "pendingTasks": [
        "change.password"
    ],
    "loginDomainID": "siteusers.acmepaymentscorp",
    "loginState": "login.inprocess",
    "authTokenValidUntil": "2018-08-01T19:15:10.404Z",
    "avatarURL": "http://api.acmepaymentscorp.com/api/users/avatar/_VeOpbQ0ztsM0WHiH3iUkBYg",
    "pendingNotifications": 0
}

Sample response body #2

The example below shows a scenario where the user must accept a pending legal agreement. Until the legal agreement is accepted, the login process isn't complete. Tokens have been abbreviated.

If there is a pending legal agreement, you must invoke the POST /api/legals/agreements operation, part of the Legals service, so that the user can accept the legal agreement and complete the login process.

{
  "loginDomainID" : "siteusers.acmepaymentscorp",
  "pendingTasks" : [ "force.accept.agreements" ],
  "loginState" : "login.inprocess",
  "avatarURL" : "http://{hostname}/api/users/1d75a0e7-b805-4152-baa0-2f9978711d6e.acmepaymentscorp/avatar",
  "pendingAgreements" : [ "signupagrmtv1.acmepaymentscorp" ],
  "pendingNotifications" : 0,
  "status" : "success",
  "authTokenValidUntil" : "2016-01-01T00:00:00.410Z",
  "userName" : "PhilipPirrip",
  "userFDN" : "1d75a0e7-b805-4152-baa0-2f9978711d6e.acmepaymentscorp",
}

Sample response body #3

In the example below, login is not yet complete because the user must provide answers to the security challenge questions. Tokens have been abbreviated.

To complete this task using the API, invoke the PUT /api/users/{UserID}/challenges operation.

{
  "loginDomainID" : "siteusers.acmepaymentscorp",
  "pendingTasks" : [ "collect.security.question.answers" ],
  "loginState" : "login.inprocess",
  "avatarURL" : "http://{hostname}/api/users/1d75a0e7-b805-4152-baa0-2f9978711d6e.acmepaymentscorp/avatar",
  "pendingNotifications" : 0,
  "status" : "success",
  "authTokenValidUntil" : "2016-01-01T00:00:00.410Z",
  "userName" : "PhilipPirrip",
  "userFDN" : "1d75a0e7-b805-4152-baa0-2f9978711d6e.acmepaymentscorp",
}

Sample response body #4

The example below shows a LoginResponse object returned when a user has completed all pending tasks, or when a user signs in under normal circumstances; there are no pending tasks, just a simple login. Tokens have been abbreviated.

{
  "userFDN" : "4fa1a6c9-c846-4186-87c1-7dab542aad22.acmepaymentscorp",
  "userName" : "adminAtmosphere",
  "loginDomainID" : "siteusers.acmepaymentscorp",
  "loginState" : "login.complete",
  "sessionValidUntil" : "2016-01-14T18:15:53.538Z",
  "authTokenValidUntil" : "2016-01-14T17:47:53.812Z",
  "avatarURL" : "http://www.acmepaymentscorp.com/api/users/avatar/_VCpiEj0keo1zHfcA_5usV3w",
  "status" : "success",
  "pendingNotifications" : 0
}

Sample response body #5

The example below shows a LoginResponse object returned when a user is logging in and two-factor authentication is set up on the platform, with delivery options for the authentication code. The user must choose a delivery mechanism and then complete the two-factor authentication process, putting in the verification code, before completing any additional pending login tasks.

{
  "status" : "success",
  "userName" : "JaneMead",
  "pendingAgreements" : [ "signupagrmtv1.acmepaymentscorp" ],
  "pendingTaskData" : {
    "2fa.required" : {
      "codeLength" : 6,
      "codeValidFor" : 300,
      "deliveryOptions" : [ {
        "target" : "*************@acmepaymentscorp.com",
        "targetType" : "Email",
        "deliveryMechanism" : "Email",
        "deliveryTargetKey" : "7jiuw9TkN6T8kbcvhq/hV45nWeHzLPruN0NNtav4HxWVurpaecfO9PK3kglvGzUH7sSaFCsceuTWbylBzAOwow=="
      }, {
        "target" : "***-***-2463",
        "targetType" : "Phone",
        "deliveryMechanism" : "Voice",
        "deliveryTargetKey" : "9pYvAYrP58nleQrV7KYiSS9ktisEc6RO7evmugUm+36b7BoHnIVJHbLc/fzrmbyY"
      }, {
        "target" : "***-***-2463",
        "targetType" : "Phone",
        "deliveryMechanism" : "Text",
        "deliveryTargetKey" : "+GqJt3MD4MGGJrVkIH5hg6EEOrdyzD9pJu8SlfUUo5zUpzJhczS7Ag=="
      } ],
      "attemptsLeft" : 3,
      "codeSent" : false
    }
  },
  "pendingTasks" : [ "2fa.required" ],
  "avatarURL" : "http://{hostname}/api/users/df492b7e-ce2a-478c-86d2-b0bf09c27e52.acmepaymentscorp/avatar"
  "userFDN" : "4e57ead2-4e61-4d7a-8b34-95d3c0ae2bc3.acmepaymentscorp",
  "loginState" : "login.inprocess",
  "pendingNotifications" : 0,
  "loginDomainID" : "siteusers.acmepaymentscorp"
}

Sample response body #6

The example below shows a LoginResponse object returned when a user is logging in and two-factor authentication (2FA) is set up on the platform, with only one delivery option, email (the platform default).

{
  "status" : "success",
  "userName" : "JaneMead",
  "pendingAgreements" : [ "signupagrmtv1.acmepaymentscorp" ],
  "pendingTaskData" : {
    "2fa.required" : {
      "target" : "*************@acmepaymentscorp.com",
      "targetType" : "Email",
      "status" : {
        "status" : "Success"
      },
      "codeLength" : 6,
      "codeValidFor" : 300,
      "deliveryOptions" : [ {
        "target" : "*************@acmepaymentscorp.com",
        "targetType" : "Email",
        "deliveryMechanism" : "Email",
        "deliveryTargetKey" : "+88ZidsUU03JzQxiZWILHAY4exsijs0iwJSy5iW4SgjSC9/v7N8rLu+zdJkttnHVsZWy91aYS1dTtpEnMlKzXg=="
      } ],
      "attemptsLeft" : 3,
      "deliveryMechanism" : "Email",
      "codeSent" : true
    }
  },
  "pendingTasks" : [ "2fa.required" ],
  "avatarURL" : "http://{hostname}/api/users/df492b7e-ce2a-478c-86d2-b0bf09c27e52.acmepaymentscorp/avatar"
  "userFDN" : "da612fdd-ca13-46a3-9cc0-86598f7b22e3.acmepaymentscorp",
  "loginState" : "login.inprocess",
  "pendingNotifications" : 0,
  "loginDomainID" : "siteusers.acmepaymentscorp"
}

Response Headers

For general information on response header values, refer to HTTP Response Headers.

Header	Description
Content-Type	application/json, application/vnd.soa.v71+json, application/vnd.soa.v72+json, application/vnd.soa.v80+json, application/vnd.soa.v81+json
Set-Cookie	The AtmoAuthToken_{fedmemberid} cookie is returned in the response when the user is fully logged in.

Response Body

Name	Type	Description
LoginResponse	LoginResponse	Contains information returned as a result of logging in. User name and FDN, along with an authorization token and the pending notifications count for the user.

Error Codes/Messages

If the call is unsuccessful an error code/message is returned. One or more examples of possible errors for this operation are shown below.

Item	Value
404	The resource could not be found. For example, you might get this if one or more of the headers is missing or has a wrong value.
500	An error occurred processing the call.

More information about Akana API Platform API error messages.

Related Topics