NAV Navbar
cURL

Introduction

The LogonLabs REST API allows you to offer Single Sign-on (SSO) to your users without the need to manage multiple complex integrations with identity providers (such as Google or Microsoft). Integrating with LogonLabs is simple and can be implemented with as few as two calls to our client API libraries. Alternatively, all of our REST APIs can be consumed directly as outlined by the documentation below.


API Libraries

Client API libraries are available in several programming languages.

Client Only Libraries

Client only libraries are used to initiate the authentication process and handle any of the custom UI portions of the login workflow. Client based libraries cannot handle the full SSO workflow so please use one of the Server side libraries to complete the login process.

js-image

Server Libraries

Server side libraries support the complete SSO workflow. They can be used to initiate the login process as well as facilitate the post-login validation workflows.

php-image dotnet-image java-image python-image nodejs-image


Authentication

The LogonLabs API acts as a broker for identity providers. To initiate a login request you simply post to our authorization interface with the required information.

For a subset of API calls, (ValidateLogin, CreateEvent, UpdateEvent), you need to pass your app_id and app_secret for authentication. These can be found here: https://app.logonlabs.com/app/#/app-settings and here: https://app.logonlabs.com/app/#/app-secrets.

Error Handling

LogonLabs uses HTTP response codes and custom error codes in the response to indicate the success or failure of a request.

Error Codes

General Error Code Response

{
  "error":
  {
    "message":"The API key provided is invalid.",
    "code":"api_error"
  }
} 
Code Meaning
api_error General API error.
validation_error There are issues with one or more parameters passed in the request.
forbidden_error The current user is not allowed to access that resource.
unauthorized_error The user needs to authenticate with the API.

HTTP Status Descriptions

Code Meaning
200 - OK All good
302 - Redirect Used by the browser during the redirection workflows for authentication.
400 - Bad Request Bad request or invalid application configuration.
401 - Unauthorized Request not authorized.
403 - Forbidden User not allowed to perform the action on specified resource.
404 - Not Found Could not find requested resource.
500 - Internal Server Error Error with the LogonLabs service.

API Reference

GetProviders

GET /providers

$ curl -L https://api.logonlabs.com/providers?app_id={your-app-id}&email_address={example@logonlabs.com}

REQUEST

GetProviders Request Object

{
  "app_id": "55cab64a7d6246b498e8cb9c9e02e1fb",
  "email_address": "example@logonlabs.com"
}

Request Parameters

Parameter Type Description
app_id string Unique identifier for your application. Provided by LogonLabs.
email_address string (optional) If specific providers have been set for a domain they will be applied based off the user's email_address.

 

Response Parameters

Parameter Type Description
identity_providers Provider[] A list of all social providers available to use for StartLogin.
enterprise_identity_providers EnterpriseProvider[] A list of all custom enterprise providers available to use for StartLogin.
suggested_identity_provider string The best matching provider available for StartLogin based on the email_address passed in the request.

Provider

Parameter Type Description
type string The type of the Identity Provider.

EnterpriseProvider

Parameter Type Description
identity_provider_id string The unique identifier for the provider.
name string The name assigned to the enterprise provider during configuration.
type string The type of the provider.

Identity Providers

Type Note
google GMail and GSuite
microsoft Office365 and Live
facebook Facebook
linkedin LinkedIn
slack Slack
github GitHub
okta Okta
quickbooks Quickbooks
onelogin OneLogin

StartLogin

POST /start

$ curl -X POST \
  -d app_id="{your-app-id}" \
  -d identity_provider="microsoft" \
  -d email_address="example@logonlabs.com" \
  -d client_data="data-required-by-my-application" \
  -d client_encryption_key="optional-key-for-aes-encryption" \
  -d tags="[{key:\"tag-name\",value:\"tag-value\"}]" \
https://api.logonlabs.com/start

This call initiates the LogonLabs brokered SSO process. Upon successful completion it returns a token to be used for redirection to the specified identity provider.

REQUEST

StartLogin Request Object

{
  "app_id": "c4ec34ecfdbf40dd853ba44a85c3b5a9",
  "identity_provider": "microsoft",
  "email_address": "example@logonlabs.com",
  "client_data": "{\"SomeData\":\"ToBeRetrieved-Via-ValidateLogin\"}",
  "client_encryption_key": "aes-encryption-key",
  "tags": [{
    "key": "tag-name",
    "value": "tag-value"
  }]
}

Request Parameters

Parameter Type Description
app_id string Unique identifier for your application. Provided by LogonLabs.
identity_provider IdentityProvider The identity provider that the user is redirected to for authentication.
email_address string (optional) Gives a hint to the Identity Provider so the user does not need to enter their email on the sign on page. It also restricts the login attempt to this email address.
client_data string (optional) Used to carry state information in your application. This string value (can be JSON) will be passed to the callback at the end of the authentication workflow.
client_encryption_key string (optional) Used to secure the transmission of session token or other sensitive web application values between your application's front and back ends.
tags Tag Used to mark the action with custom key/value pairs that are queryable later via the LogonLabs dashboard.

Tag

Parameter Type
key string
value string

Identity Providers

Type Note
google GMail and GSuite
microsoft Office365 and Live
facebook Facebook
linkedin LinkedIn
slack Slack
github GitHub
okta Okta
quickbooks Quickbooks
onelogin OneLogin

RESPONSE

StartLogin Response Object

{
  "token": "55cab64a7d6246b498e8cb9c9e02e1fb"
}

Response Parameters

Parameter Type Description
token string The unique identifier to continue the login process via RedirectLogin.

RedirectLogin

GET /redirect

$ curl -L https://api.logonlabs.com/redirect?token={your-token}

REQUEST

RedirectLogin Request Object

{
  "token": "55cab64a7d6246b498e8cb9c9e02e1fb"
}

Request Parameters

Parameter Type Description
token string The unique identifier returned by StartLogin

 

RESPONSE

This call returns a 302 Redirect to the chosen provider. When the user finishes entering authentication credentials they are redirected back to the callback url specified in your settings at https://app.logonlabs.com/app/#/app-settings. The callback url will have a token in the query string that is used to retrieve the login results via ValidateLogin.


ValidateLogin

POST /validate

$ curl -X POST \
  -H "x-app-secret: {your-app-secret}" \
  -d app_id="{your-app-id}" \
  -d token="{your-token}" \
https://api.logonlabs.com/validate

This call validates a login with an identity provider and enforces any IP Address, Geographical or Time Restrictions. It then retrieves all the login information from the identity provider. Requires your app secret.

REQUEST

ValidateLogin Request Object

{
  "app_id": "c4ec34ecfdbf40dd853ba44a85c3b5a9",
  "token": "dff6f006227b4f2f809e36bb967eff97"
}

Request Headers

Header Description
x-app-secret Your app secret (user's app_secrets can be found at https://app.logonlabs.com/app/#/app-secrets).

Request Parameters

Parameter Type Description
app_id string Unique identifier for your application.
token string The unique identifier to retrieve the response data package. Found in the query string of the redirection url.

RESPONSE

ValidateLogin Response Object

{
  "app_id": "c4ec34ecfdbf40dd853ba44a85c3b5a9",
  "event_id": "660ecc44208441af8d54946ae2903fc5",
  "email_address": "example@logonlabs.com",
  "ip_address": "1.2.3.4",
  "event_success": true,
  "validation_details": {
    "auth_validation": "Pass",
    "email_match_validation": "Pass",
    "ip_validation": "Pass",
    "geo_validation": "Pass",
    "time_validation": "Pass"
  },
  "identity_provider_data": {
    "identity_provider_type": "microsoft",
    "uid": "",
    "first_name": "FirstName",
    "last_name": "LastName",
  },
  "location": {
    "country_name": "Canada",
    "country_code": "CA",
    "continent_name": "North America",
    "continent_code": "NA"
  },
  "client_data": "{\"SomeData\":\"ThatWasSet-Via-StartLogin\"}",
}

Response Parameters

Parameter Type Description
app_id string Unique identifier for your application.
event_id string Unique identifier for the event.
email_address string Email address of the user authorized by the Identity Provider.
ip_address string IP of the user attempting to authenticate.
event_success boolean This confirms that authorization from the Identity Provider along with all custom validations succeeded.
validation_details ValidationDetails (object) This object contains all validations about the login attempt. This includes both authorization from the Identity Provider as well as Restriction validations.
identity_provider_data IdentityProviderData (object) This object contains the data that was returned from the Identity Provider authorization.
location_details LocationDetails (object) Location details for where the request originated. Note: Based on the IP address.
client_data string (optional) Used to carry state information in your application. This string value (can be JSON) will be passed to the callback at the end of the authentication workflow.

ValidationDetails

Parameter Type Description
auth_validation EventValidationTypes This validation confirms that the Identity Provider has authorized the user.
email_match_valid EventValidationTypes This validation confirms that the optional email_address passed in the initial Authentication request was the email_address that was authorized by the Identity Provider. If not entered it is returned as NotApplicable.
ip_validation EventValidationTypes This validation confirms that the request's IP address passes IP Restrictions set in https://app.logonlabs.com/app/#/default-rules or https://app.logonlabs.com/app/#/domain-rules. If no restrictions are set, the value is NotApplicable.
geo_validation EventValidationTypes This validation confirms that the IP address location is valid when compared against the GeoFence Restrictions set in https://app.logonlabs.com/app/#/default-rules or https://app.logonlabs.com/app/#/domain-rules. If no restrictions are set, the value is NotApplicable.
time_validation EventValidationTypes This validation confirms that the requests start time is valid when compared against the Time Restrictions set in https://app.logonlabs.com/app/#/default-rules or https://app.logonlabs.com/app/#/domain-rules. If no restrictions are set, the value is NotApplicable.

IdentityProviderData

Parameter Type Description
identity_provider_type IdentityProvider The identity provider that was used for authentication.
uid string This is a unique identifier created by the Identity Provider for the user.
first_name string The first name of the user provided by the Identity Provider.
last_name string The last name of the user provided by the Identity Provider.

EventValidationTypes

Type Description
Pass Validation succeeded
Fail Validation failed
NotApplicable Validation was skipped or not applicable for workflow

Identity Providers

Type Note
google GMail and GSuite
microsoft Office365 and Live
facebook Facebook
linkedin LinkedIn
slack Slack
github GitHub
okta Okta
quickbooks Quickbooks
onelogin OneLogin

LocationDetails

Parameter Type Description
continent_code string Short 2 letter continent code based on the IP address of the user.
continent_name string Full name of the continent based on the IP address of the user.
country_code string Short 2 letter continent code based on the IP address of the user.
country_name string Full name of the country based on the IP address of the user.

CreateEvent

POST /event

$ curl -X POST \
  -H "x-app-secret: {your-app-secret}" \
  -d app_id="{your-app-id}" \
  -d type="LocalLogout" \
  -d validate=false \
  -d event_success=true \
  -d first_name="FirstName" \
  -d last_name="LastName" \
  -d ip_address="1.2.3.4" \
  -d user_agent="Mozilla/5.0" \
  -d tags="[{key:\"tag-name\",value:\"tag-value\"}]" \
https://api.logonlabs.com/event

This call allows the client to manually create events that can be later retrieved via the Event Logs page in the Logon Labs dashboard https://app.logonlabs.com/app/#/dashboard. Requires your app secret.

REQUEST

CreateEvent Request Object

{
  "app_id": "c4ec34ecfdbf40dd853ba44a85c3b5a9",
  "type": "LocalLogin",
  "validate": true,
  "local_validation": "Pass",
  "email_address": "example@logonlabs.com",
  "first_name": "FirstName",
  "last_name": "LastName",
  "ip_address": "1.2.3.4",
  "user_agent": "Mozilla/5.0",
  "tags": [{
    "key": "tag-name",
    "value": "tag-value"
  }]
}

Request Headers

Header Description
x-app-secret Your app secret (user's app_secrets can be found at https://app.logonlabs.com/app/#/app-secrets).

Request Parameters

Parameter Type Description
app_id string Unique identifier for your application. Provided by LogonLabs.
type string Designates the event type. Allowable values: LocalLogin and LocalLogout.
validate boolean Indicates whether this event should have any restriction checks performed on it. If validation fails the validation_details will contain complete information on the failure.
local_validation EventValidationTypes Indicates whether the action succeeded in the consumer's system. Set to NotApplicable if this does not apply to your workflow.
email_address string The email address of the user performing the action.
first_name string The first name of the user performing the action.
last_name string The last name of the user performing the action.
ip_address string The ip address of the user performing the action.
user_agent string The user agent of the client.
tags Tag Marks the event with custom key/value pairs that are queryable later via the Logon Labs dashboard.

EventValidationTypes

Type Description
Pass Validation succeeded
Fail Validation failed
NotApplicable Validation was skipped or not applicable for workflow

Tag

Parameter Type
key string
value string

RESPONSE

CreateEvent Response Object

{
  "event_id": "660ecc44208441af8d54946ae2903fc5",
  "event_success": false,
  "validation_details": {
    "ip_validation": "Pass",
    "time_validation": "Fail",
    "geo_validation": "NotApplicable"
  },
  "location": {
    "country_name": "Canada",
    "country_code": "CA",
    "continent_name": "North America",
    "continent_code": "NA"
  }
}

Response Parameters

Parameter Type Description
event_id string Unique identifier for the event.
event_success boolean This confirms that all custom validations succeeded.
validation_details ValidationDetails This object contains all validations about the login attempt. This includes both authorization from the Identity Provider as well as Restriction validations.
location LocationDetails Location details for where the request originated. Note: Based on the IP address.

ValidationDetails

Parameter Type Description
auth_validation EventValidationTypes This validation returns as NotApplicable for CreateEvent
email_match_valid EventValidationTypes This validation returns as NotApplicable for CreateEvent
ip_validation EventValidationTypes This validation confirms that the request's IP address passes IP Restrictions set in https://app.logonlabs.com/app/#/default-rules or https://app.logonlabs.com/app/#/domain-rules. If no restrictions are set, the value is NotApplicable.
geo_validation EventValidationTypes This validation confirms that the IP address location is valid when compared against the GeoFence Restrictions set in https://app.logonlabs.com/app/#/default-rules or https://app.logonlabs.com/app/#/domain-rules. If no restrictions are set, the value is NotApplicable.
time_validation EventValidationTypes This validation confirms that the requests start time is valid when compared against the Time Restrictions set in https://app.logonlabs.com/app/#/default-rules or https://app.logonlabs.com/app/#/domain-rules If no restrictions are set, the value is NotApplicable.

EventValidationTypes

Type Description
Pass Validation succeeded
Fail Validation failed
NotApplicable Validation was skipped or not applicable for workflow

LocationDetails

Parameter Type Description
continent_code string Short 2 letter continent code based on the IP address of the user.
continent_name string Full name of the continent based on the IP address of the user.
country_code string Short 2 letter continent code based on the IP address of the user.
country_name string Full name of the country based on the IP address of the user.

UpdateEvent

PUT /event/{event_id}

$ curl -X PUT \
  -H "x-app-secret: {your-app-secret}" \
  -d app_id="{your-app-id}" \
  -d event_success=false \
  -d tags="[{key:\"tag-name\",value:\"tag-value\"}]" \
https://api.logonlabs.com/event/{event_id}

This call allows the client to manually update events. Usually this is to indicate failure/success within the client's system and provide that information to Logon Labs. These events can be viewed in the Logon Labs dashboard at: https://app.logonlabs.com/app/#/dashboard. Requires your app secret.

REQUEST

UpdateEvent Request Object

{
  "event_id": "ad2a2fbf6ae44be68dc96799b6650def",
  "app_id": "c4ec34ecfdbf40dd853ba44a85c3b5a9",
  "local_validation": "Fail",
  "tags": [
    {
      "key": "tag-name",
      "value": "tag-value"
    }
  ]
}

Request Headers

Header Description
x-app-secret Your app secret (user's app_secrets can be found at https://app.logonlabs.com/app/#/app-secrets).

Request Parameters

Parameter Type Description
event_id string Unique identifier for the event.
app_id string Unique identifier for your application. Provided by LogonLabs.
local_validation EventValidationTypes Indicates whether the event succeeded.
tags Tag Used to mark the action with custom key/value pairs that are queryable later via the LogonLabs dashboard. Existing tags will be overwritten.

EventValidationTypes

Type Description
Pass Validation succeeded
Fail Validation failed
NotApplicable Validation was skipped or not applicable for workflow

Tag

Parameter Type
key string
value string

 

RESPONSE

Returns HTTP 200 and empty response body on success.


Callback URL

After redirecting the user to the desired Identity Provider, the Callback URL is how control is transferred from the Logon Labs back to your website.

Once a user has authenticated with an Identity Provider, Logon Labs will invoke your Callback URL with an 'app_id' and 'token' as query string parameters. Your website will need to implement code that gets the 'token' from the query string and then calls 'ValidateLogin' to determine if the login attempt was a success. After checking the results of 'ValidateLogin', the normal workflow of authenticating a user can resume (ie. creating the users session, creating cookies, redirecting to a default page, etc).