Authentication

The Lastline API supports account-based authentication.

Since the API is always accessed over https, the authentication parameters are never sent in clear-text and can be sent using unencoded ASCII text.

Account-Based Authentication

For account-based authentication, all Lastline API methods require two parameters:

  • username: Lastline portal account username
  • password: Lastline portal account password

Authentication Methods

To explicitly authenticate with the API, a client can send credentials to the login() method. In addition to the response code, the API returns a session cookie which must be included in all subsequent requests to the API.

Alternatively, if any non-authentication method is called without the required session cookie, the client can include credentials directly as parameters to the called API method. The API will validate credentials and, if authentication was successful, forward the request to the originally called method and include the session cookie in the response of the called method.

Therefore, all methods in the Lastline API accept the authentication credentials as parameters and can return authentication-related error codes. These parameters and error codes are excluded from the documentation of the individual API methods.

Quick-Start

To test your Lastline API credentials, you will need to make an HTTP POST request to the login API method, providing your username and password as form parameters. As an example, this can be achieved as follows using the curl command-line utility:

curl -X POST "https://user.lastline.com/papi/login" -d "username=USERNAME&password=PASSWORD"

This will authenticate using your account, providing an output similar to the example shown below:

{"success": 1, "data": "true"}

The session cookie obtained from the login API request can be used to perform further API calls, as demonstrated by the following example, once again using the curl utility:

curl -X POST "https://user.lastline.com/papi/login" -d "username=USERNAME&password=PASSWORD" -c lastline-cookie
curl -X POST "https://user.lastline.com/papi/ping" -b lastline-cookie

Here, the ping() API method was used as a test, and should output:

{"success": 1, "data": "pong"}

Method Index

  • login():

    Authenticate and start a session.

  • logout():

    Terminate an existing session.

  • ping():

    Test an existing session.

Method Documentation

authentication.login(response_format)

Authenticate with the API.

URL

/papi/login[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

GET/POST Parameters

  • username:

    Lastline portal username. (required)

  • password:

    Lastline portal password. (required)

Contents of successful response

“true”

Error Codes

authentication.logout(response_format)

Destroy authenticated session.

URL

/papi/logout[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

Contents of successful response

“true”
authentication.ping(response_format)

Validate authenticated session.

URL

/papi/ping[. response_format]

response_format can be xml or json (defaults to json)

HTTP METHOD

GET or POST

Contents of successful response

“pong”

Response Format

The format of API responses can be selected by appending an extension to the request URL. Supported formats are JSON and XML. If no extension is provided, the format defaults to JSON. JSON is the recommended format for automated processing, while XML is recommended for human consumption (since modern browsers make it readable by pretty-printing it).

A successful response comes in the form:

{"success": 1, "data": ...}

A failed response will return:

{"success": 0, "error_code": <ERROR_CODE>, "error": <ERROR_MESSAGE>}

The error_code field is optional.

Timestamps

By default, timestamps returned by the Lastline API are in UTC. Specific APIs accept timezone/time_zone as parameters. In such cases, all returned timestamps are converted into the requested timezone. Support for timezone/time_zone is documented in the respective APIs.

Error Codes

The Lastline API uses error-codes for reporting errors. Errors related to authentication or general mis-use of the API are documented below. Additionally, each API module provides error-codes for module-specific errors.

LLAPI_ERROR_UNSUPPORTED_FORMAT

Error code 1: Returned when requesting an unsupported API format.

LLAPI_ERROR_NO_DATA_FOUND

Error code 2: Generic error returned when requesting data that is (currently) not available.

LLAPI_ERROR__AUTHENTICATION_ERROR

Error code 3004: Returned when requesting results with invalid credentials.

LLAPI_ERROR__PERMISSION_DENIED

Error code 3001: Returned when requesting a resource that the user or license is not permitted to access.

LLAPI_ERROR__INVALID_PARAMETER

Error code 3005: returned when sending a request with an invalid parameter.

LLAPI_ERROR__MISSING_PARAMETER

Error code 3006: returned when sending a request that is missing a required parameter.

LLAPI_ERROR__NO_SUCH_ENTITY

Error code 3007: returned when requesting an entity that does not exist.

LLAPI_ERROR__DUPLICATE_ENTITY

Error code 3008: returned when trying to add an entity that conflicts with an already existing entity.

LLAPI_ERROR__CUSTOMER_SHARD_NOT_FOUND

Error code 3009: returned when trying to access a customer shard that does not exist.

LLAPI_ERROR__UNSUPPORTED_FEATURE

Error code 3010: returned when an operation is requested on an appliance that does not support the feature.

LLAPI_ERROR__ENTITY_NOT_IN_STORAGE
Error code 3011: Returned when attempting to access an
entity that is not available in storage. This could indicate that entity was deleted by data retention or was not persistently stored in the first place.
LLAPI_ERROR__ENTITY_IN_USE

Error code 3012: returned when interaction with an entity is blocked because it’s being used.

LLAPI_ERROR__NOT_YET_AVAILABLE

Error code 3013: returned when requesting an entity that is not yet created or processed.

LLAPI_ERROR__TOO_MANY_REQUESTS

Error code 3014: returned when the user or license has momentarily exceeded the allowed number of accesses.

LLAPI_ERROR__HOSTED_BACKEND_UNVAILABLE

Error code 3015: returned when an on-premise API instance temporarily fails to reach the hosted API instance requested.

LLAPI_ERROR__PASSWORD_REQUIRED

Error code 3016: returned when trying to perform an operation without providing the required password.

LLAPI_ERROR__DUPLICATE_OPERATION

Error code 3017: returned when trying to perform an operation that has already been executed.

LLAPI_ERROR__TEMPORARILY_UNAVAILABLE

Error code 3018: Returned when the request cannot be satisfied due to a temporary issue.

LLAPI_ERROR__WRONG_DATACENTER

Error code 3019: Returned when a request to Lastline’s hosted backend infrastructure was sent to the wrong data-center. Client should submit the request to the correct datacenter instead.