REST API reference

Owned by Nicole Hühn
Last updated: Aug 27, 2020
4 min read

Purpose

There are multiple native and non-native apps from the Jira and Confluence product range that are available for smartphones and can be downloaded via the App Store or Play Store. However, those apps do not include a two-factor authentication for the login process. In order to implement this functionality in their apps, mobile app vendors have requested an API to support the second factor (which Secure Login provides) in their apps. To enable a two-factor authentication with Secure Login, the Secure Login API provided by syracom offers a set of necessary endpoints that allow an app to authenticate a second factor.

Overview

This authentication is linked with an HTTP session, which means that all of the apps requests must be done within the same session. In case the session has expired or was invalidated, the user has to do a new authentication. As all requests to the API must be authorized by the server, the API takes the username from the current HTTP session. The URL of the API depends on your installation, but generally follows the schema:

https://<baseURL>/<contextPath>/rest/securelogin−admin/1.0/api/<endpoint>

So, for example, if you use Jira at my.shiny.server on port 2048 with the context path /jira, then the URL of the /info endpoint is:

https://my.shiny.server:2048/jira/rest/securelogin−admin/1.0/api/info

The API contains three endpoints:

endpoint

description

endpoint

description

/info

Provides general information about Secure Login.

/user

Provides information about the current state of the user.

/auth

Authenticates the user of the current HTTP session.

The usual call flow will first call /info to make sure the plugin is active and ready to work.
If the plugin is inactive, nothing else needs to be done and the app proceeds. It is recommended to check from time to time if the plugin got activated.
If the plugin is active, the app compares the timestamp that came with the response to see if there are any time drifts to consider.

The next call goes to /user, which delivers information about the users status from the perspective of Secure Login.
The returned data indicates whether the user:

  • has to enter his or her PIN or

  • has to do the onboarding process or

  • is blocked (information about the reason for and duration of the block are provided)

If the user has to enter his or her PIN, then the next call will go to the endpoint /auth, which submits the PIN. On a correct PIN, Secure Login will validate the current HTTP session, and the user is authenticated.

Attention: If the app is installed on a phone that changes between different IP networks (for example if you connect to a different WiFi), then use the /info endpoint to check whether the user has to (re-)enter the PIN or is still authenticated.

What if the user enters a wrong PIN?
After having entered a wrong PIN, the user can retry to enter the PIN as long as he or she has not been blocked. How many retries the user has until being blocked depends on the settings the administrator made.

The administrator can specify

  • after how many incorrect PINs the user is blocked and

  • for how long the user is blocked.

For more information, see the Administrator's Guide.

Resources

api/info

Gets the information whether Secure Login is enabled in the system and what the server time is.

Request - Query Parameters

None

Responses

Status 200 - application/json

Response fields

field

type

description

field

type

description

active

boolean

Is true when the plugin is active, else false.

server_time

string

The server date and time in ISO-8601, changed to GMT. It is informal to give the opportunity of fixing time drifts.

Examples

{ "active": true, "server_time": "1991−08−17T07:00:00Z" }
{ "active": false, "server_time": "1991−08−17T07:00:00Z" }

api/user

Get information from Secure Login related to the current user.

Request - Query Parameters

The username is taken from the current HTTP session, so no parameter to submit.

Responses

Status 200 - application/json
The request was completed successfully.

Status 410 - application/json
The request was aborted, because the plugin is not active.

Response fields

field

type

description

field

type

description

state

string

can take one of these values:

enter - the user has to enter the PIN
bypass - no action is needed
onboarding - the user has not completed the onboarding process yet. The onboarding process must be completed in a desktop browser.
blocked - currently, the user cannot proceed because the account is blocked.

blocked

structure

This is only available if status == blocked and contains details.

Structure fields:
reason - Indicates why the account is blocked. Its only value is brute_force – too many PIN failures.
until - Indicates until when the account is blocked. The timestamp format is in ISO- 8601 format and at time zone GMT.

Examples

{ "state": "enter" }

api/auth

Submit the PIN to authenticate the current HTTP session for the current user.

Request - Query Parameters

The username is taken from the current HTTP session. The PIN is posted with a Content-Type of text/plain as a sequence of numbers without any prefix or suffix and without any spacing. Just the string like 910817.

Responses

Status 200 - no response body
The request was completed successfully and the session is authenticated.

Status 401 - no response body
The authentication failed.

Status 406 - no response body
The user still has onboarding status and cannot be authenticated yet.

Status 410 - no response body
The request was aborted because the app is not active.

Response fields

None

Examples

None