Lastwall Secure Login API

Message based authentication. A collection of API calls to integrate an existing authentication system with Lastwall Networks Inc. 2-factor authentication system.

Overview

Integration docs coming soon. Sample code for Node.js also coming soon!

API Calls

All API calls should be prefixed with the following address: https://api.lastwall.com/api/. For example, to perform a GET on /sessions, you would use the following URL: https://api.lastwall.com/api/sessions

Parameters for all API calls (GET, PUT, POST, and DELETE) should be included as JSON in the message body. For GET requests, parameters may be included either in the request URL or in the message body.

NOTE: remember to set the Content-Type request header to application/json to indicate a JSON-formatted message body.

API Security

We offer two security models for API requests: Basic (simple) and Digest (more secure). If your goal is to simplify and speed up the integration process, we recommend basic authentication. For enhanced security, we recommend the digest model. You may enable either security model, or both, in your service settings.

Both models require a two-part API key: a public token and a private, secret key. Your private key must be stored in a secure environment, as it is used to ensure the identity of our customers during API requests. Do NOT share or publish your private key!

If you do not have an API key, please visit the Lastwall website to request one.

HTTP Basic Authentication

Lastwall API calls using basic authentication must be sent with the following request header:

• Authorization - a standard HTTP Basic Authentication header

To construct the header value, take your API public token and secret key, and treat them as a user name and password using standard HTTP basic auth.

Example: lets say your API public token is "test" and your secret key is "secret". Then the header value is the base-64 encoding of the string "test:secret", preceded by the word "Basic" and a separating space. This results in the following header value: "Basic dGVzdDpzZWNyZXQ="

For more information on HTTP Basic Authentication, see Basic Authenticaion

Digest Authentication

Lastwall API calls using digest authentication must be sent with the following request headers:

• X-Lastwall-Token - The public token part of the API key
• X-Lastwall-Timestamp - The time at which the request was sent. Must match the Lastwall server time within 5 minutes
• X-Lastwall-Request-Id - A unique ID representing this request. Can be any globally-unique string (eg. a random UUID)
• X-Lastwall-Signature - The request signature, described below

The request signature is calculated in the following way:

1. Take the full URL of the request, excluding any parameters (eg. https://api.lastwall.com/api/sessions)
2. Append the request timestamp to the URL string
3. Append the unique request ID to the resulting string
4. Sign the resulting string with an HMAC-SHA1 using your private api key

Our server will use the public token and request signature to confirm that you are authorized to use this service. The exact timestamp and request ID must be provided so that we can create the same signature on the server and verify authenticity.

For examples and sample code, please see our helper libraries

API Return Values

All Lastwall API calls will return one of the following status codes:

• 200 - OK: the API call was successful
• 400 - Error: the API call failed due to invalid input or caller error
• 401 - Authorization Error: the API call failed due to an API key authentication failure
• 500 - Fatal: the API call failed due to an internal Lastwall system error (not your fault)

For all successful API calls (code 200), the relevant response data will be returned as JSON in the message body. If there is no data to return, the result will be:

{ "status": "OK" }

For all failed API calls (codes 400, 401, or 500), the result will be:

{ "status": "Error", "error": "(specific error message)" }

GET - /verify

Verifies an API key. Use this as a testing tool to make sure you have correctly set your Lastwall security request headers.

Required Parameters

• none

Return Values

• none

Examples

Request: curl -X GET -H "(headers)" "https://api.lastwall.com/api/verify"

Response 1: HTTP/1.1 200 OK { "status": "OK" }

Response 2: HTTP/1.1 401 Unauthorized { "status": "Error", "error": "Invalid API key" }

POST - /users

Creates a new user account and begins the activation process by sending the user an activation email.

Required Parameters

• user_id - The unique string identifier for the user. By default, only alphanumeric strings are accepted. Constraints on valid ID strings can be redefined in service settings.
• email - The user's email address. An activation email will be sent to this address to affirm the user controls it.
• phone - PSTN phone number of the user being created. The user can confirm or alter this during the registration process. Service settings may allow this field to be left blank.

Optional Parameters

• activate - A boolean indicating whether or not to begin the account activation process for the new user. Default: true
• name - The user's name. If supplied, used only to improve the user interface. Default: none

Return Values

• none

Examples

Request: curl -X POST -H "(headers)" "https://api.lastwall.com/api/users" -d '{"user_id":"tester","name":"Beta","email":"[email protected]","phone":"18001234567"}'

Response: HTTP/1.1 200 OK { "status": "OK" }

GET - /users

Gets info on a user account.

Required Parameters

• user_id - The unique string identifier for the user. Must be a valid ID string representing an existing user account.

Return Values

• user_id - The requested user ID
• name - The user's display name
• phone - The user's registered phone number
• email - The user's email address
• enabled - Boolean value indicating whether the user account has been disabled
• activated - Boolean value indicating whether the user account has been activated
• date - The date/time when the user account was created

Examples

Request: curl -X GET -H "(headers)" "https://api.lastwall.com/api/users" -d '{"user_id":"tester"}'

Response: HTTP/1.1 200 OK

{
    "user_id": "tester",
    "name": "Beta",
    "phone": "18001234567",
    "email": "[email protected]",
    "enabled": true,
    "activated": true,
    "date": "2015-02-06T23:22:25.538Z"
}

PUT - /users

Modifies an existing user account. Warning: if you modify critical details, the user account will be deactivated. To reactivate it, you must trigger a reactivation process by setting the activate parameter in this request, or via a POST to /activate.

Required Parameters

• user_id - The unique string identifier for the user. Must be a valid ID string representing an existing user account.

Optional Parameters

• name - Change the user's display name. If supplied, used only to improve the user interface.
• email - Change the user's email address. This will force the account to be deactivated.
• phone - Change the PSTN phone number of the user being created. This will force the account to be deactivated.
• activate - If true, and if this API call forces the account to be deactivated (due to a change in email or phone), an account re-activation process will be automatically started for the user. Default: true

Return Values

• none

###Examples

Request: curl -X PUT -H "(headers)" "https://api.lastwall.com/api/users" -d '{"user_id":"tester","email":"[email protected]"}'

Response: HTTP/1.1 200 OK { "status": "OK" }

DELETE - /users

Deletes an existing user account.

Required Parameters

• user_id - The unique string identifier for the user. Must be a valid ID string representing an existing user account.

Return Values

• none

Examples

Request: curl -X DELETE -H "(headers)" "https://api.lastwall.com/api/users" -d '{"user_id":"tester"}'

Response: HTTP/1.1 200 OK { "status": "OK" }

Request: curl -X DELETE -H "(headers)" "https://api.lastwall.com/api/users" -d '{"user_id":"nonuser"}'

Response: HTTP/1.1 200 OK { "status": "Error", "error": "No user found with the given ID nonuser" }

POST - /activate

Begins an activation process for an existing user. Will immediately send an activation email to the given user, requesting them to begin a live registration session.

Required Parameters

• user_id - The unique string identifier for the user. Must be a valid ID string representing an existing user account.

Optional Parameters

• activate - A boolean indicating whether or not to begin the account activation process for the new user. If false, the user account will be immediately deactivated. Default: true

Return Values

• none

Examples

Request: curl -X POST -H "(headers)" "https://api.lastwall.com/api/activate" -d '{"user_id":"tester"}'

Response: HTTP/1.1 200 OK { "status": "OK" }

POST - /sessions

Create an authentication session for a registered user. Default session parameters can be modified in the service settings.

Required Parameters

• user_id - The unique ID of the user to create the session for.

Optional Parameters

• force_call - Forces a bypass of our risk-based policy engine and ensures that a verification call occurs. Default: false

Return Values

• session_id - ID of current authentication session. Must be kept to query the session later on
• user_id - The specified user ID for the session
• session_url - The url of the session web page, to be pulled up as an iframe on the end user's browser
• start - The time and date when the session was created
• duration - Total duration of the session thus far, in seconds
• active - Boolean value indicating whether the session is still active or has been closed
• status - String value indicating session status. Will be "Pending" until the session is resolved
• authenticated - Boolean value indicating the final result of the authentication session once it is resolved

Examples

Request: curl -X POST -H "(headers)" "https://api.lastwall.com/api/sessions" -d '{"user_id":"tester"}'"

Response: HTTP/1.1 200 OK

    {
        "session_id": "LWSA053866F136D55AE9960F7FA7C27A45B4650BAA51FF6C762",
        "user_id": "tester",
        "session_url": "https://ss1.lastwall.com/iframe/sessions/LWSA053866F136D55AE9960F7FA7C27A45B4650BAA51FF6C762",
        "start": "2015-03-12T21:37:41.065Z",
        "duration": 0.007,
        "active": true,
        "status": "Pending",
        "authenticated": false
    }

GET - /sessions

Retrieves the status of an existing session.

Required Parameters

• session_id - Session ID being inquired about.

Return Values

• session_id - ID of current authentication session
• user_id - The specified user ID for the session
• session_url - The url of the session web page, to be pulled up as an iframe on the end user's browser
• start - The time and date when the session was created
• duration - Total duration of the session thus far, in seconds
• active - Boolean value indicating whether the session is still active or has been closed
• status - String value indicating session status. Will be "Pending" until the session is resolved
• authenticated - Boolean value indicating the final result of the authentication session once it is resolved

Examples

Request: curl -X GET -H "(headers)" "https://api.lastwall.com/api/sessions" -d '{"session_id":"LWSA053866F136D55AE9960F7FA7C27A45B4650BAA51FF6C762"}'"

Response: HTTP/1.1 200 OK

{
    "session_id": "LWSA053866F136D55AE9960F7FA7C27A45B4650BAA51FF6C762",
    "user_id": "tester",
    "session_url": "https://ss1.lastwall.com/iframe/sessions/LWSA053866F136D55AE9960F7FA7C27A45B4650BAA51FF6C762",
    "start": "2015-02-07T21:37:41.065Z",
    "duration": 33.044,
    "active": false,
    "status": "Authenticated",
    "authenticated": true
}

Request: curl -X GET -H "(headers)" "https://api.lastwall.com/api/sessions"

Response: HTTP/1.1 400 Bad Request { "error": "No session ID specified" }