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 25 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

Back to top

URL

https://{hostname}/api/login

Back to top

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

Back to top

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

Back to top

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.

Back to top

Response

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

Back to top

Sample Response

The sample response below shows the user logging in. The cookie is returned in the Set-Cookie header.

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%2C
claimed_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%3DcoY4laDvxkQ4vLLg6Tkfc9X35THApqFPh3hONnbCwXsNNjaKxUu9Ce98jf88kP
EcrImd69Ry2N8XIrzICKTaUdCIni2ETKNCccpbYfBWftTQoUNVpQffzUTCP965GKqPLf6Zo0ol48TCRn4bWepqz8pycFczAhlsrl-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%3DMKd7acZkLzsMIalD2LFhmuLPy58
xa-NlxoWucWi3WVfO8UTsz_t88fCjQIQHKH-pRol_1wsGVHRnz3riAl7eKrRYEo68XOMn1UnoMYXQUX9mTGtGoTX
gu61Dk7vIIiVhBJV1AIRZiHKoDim04hq-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.

{
  "loginState" : "login.complete",
  "authTokenValidUntil" : "2017-05-25T19:31:02.477Z",
  "avatarURL" : "http://api.acmepaymentscorp.com:7900/api/users/avatar/_VeOpbQ0ztsM0WHiH3iUkBYg",
  "loginDomainID" : "siteusers.acmepaymentscorp",
  "lastLoginDate" : "2017-05-25T18:55:30Z",
  "userName" : "adminacmepaymentscorp",
  "userFDN" : "461b3899-37c6-4eb8-936b-9abf8ba74c0a.acmepaymentscorp",
  "pendingNotifications" : 0,
  "status" : "success"
}
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"
}

Back to top

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_{TenantID} cookie is returned in the response when the user is fully logged in.

Back to top

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.

Back to top

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.

Back to top

Related Topics