Auths

Path:/service/v3/auths

The sessions endpoint provides management of Service Authorization Requests

POST

Create an Authorization Request for the Service

Request

Requests will be a JWE encrypted JSON payload with the following attributes:

username (string):

LaunchKey username or Directory User Identifier of the Directory User for which you wish to create a Session

context (string) [optional]:

Data you wish to send the mobile authenticator with this request.

policy (object) [optional]:

Authorization policy for this call. The attributes of this Policy will be merged with any Service level Policy set in the Admin Center. When merging, the LaunchKey API will use the more restrictive value between the two Policies. The policy object can have the following attributes:

minimum_requirements (list) [optional]:

List of objects identifying the factor requirements for the request.

requirement (string) [optional]:Options: [authenticated, enabled] - To require any factors, authenticated is required.
any (number) [optional]:Minimum number of factors required
knowledge (number) [optional]:Options[0, 1] - Flag determining whether a knowledge factor is required
inherence (number) [optional]:Options[0, 1] - Flag determining whether an inherence factor is required
possession (number) [optional]:Options[0, 1] - Flag determining whether a possession factor is required
factors (array) [optional]:

List of objects describing auth factors with the following attributes:

factor (string):

Options: [geofence, device integrity] - The type of factor

quickfail (boolean):

Options: [true, false] - Boolean flag when true will immediately fail the auth upon failure of the factor and the mobile device will not process any remaining factors.

requirement (string):

Options: [forced requirement, allowed] - To require the factor, forced requirement is required.

priority (number):

Integer value representing the priority of the factor being presented to the user.

attributes (object):

Object with the following attributes:

factor enabled (number) [optional]:

Options[0, 1] - Flag determining whether the factor is enabled. Required for device integrity to be enabled and ignored for geofence.

locations (array) [optional]:

Required for geofence. List of location objects with the following parameters:

radius (number):A decimal value of the radius for a geofence in meters.
latitude (number):A decimal value of the latitude in degrees for the center of the geofence.
longitude (number):A decimal value of the longitude in degrees for the center of the geofence.

Example without Auth Request ID:

{"username": "my-unique-user-identifier"}

Example with Context:

{"username": "my-unique-user-identifier", "context": "Authorizing charge for $12.34 at iovation.com"}

Example with Policy:

{
    "username": "my-unique-user-identifier",
    "policy": {
        "minimum_requirements": [
            {
                "requirement": "authenticated",
                "any": 2,
                "knowledge": 0,
                "inherence": 0,
                "possession": 0
            }
        ],
        "factors": [
            {
                "factor": "geofence",
                "requirement": "forced requirement",
                "quickfail": false,
                "priority": 1,
                "attributes": {
                    "locations":[
                        {
                            "radius": 60.0,
                            "latitude": 27.175,
                            "longitude": 78.0422
                        }
                    ]
                }
            }
        ]
    }
}

Response

Responses will be a JWE encrypted JSON payload with the following attribute:

auth_request (string):Globally unique identifier for the Authorization Request. This value will be used either to get Authorization Request responses via GET or process Authorization Request responses received via Authentication Response Event.

Example:

{"auth_request": "5d1acf5c-dc5d-11e7-9ea1-0469f8dc10a5"}

GET

Get the response to an Authorization Request if it exists

Request

Path:/service/v3/auths/{auth_request}

Requests will consist of a path with the following path parameter:

auth_request (string):Globally unique identifier for the Authorization Request whose response is requested. This value would have been received via a POST call.

Example:

GET /service/v3/auths/5d1acf5c-dc5d-11e7-9ea1-0469f8dc10a5 HTTP/1.1
Host: api.launchkey.com

Response

Responses may be based on the following HTTP status codes:

200:The User has responded to the Authorization Request and the information related to the response in the the body.
204:The User has not responded to the Authorization Request but they may still respond.
408:The User has not responded to the Authorization Request and the allotted time for responding has been exceeded.

If the response status code is 200, the response body will be a JWE encrypted JSON payload with the following attributes:

auth (string):Base64 encoded RSA encrypted JSON string. This data is the user response directly from their device. It is encrypted on the device. As such, the LaunchKey Platform API has no knowledge of the contents of the encrypted data. Once Base64 decoded, decrypt the result with the private key of the RSA public/private key pair whose Key ID matches the value provided in the public_key_id element. See Auth Package below for its attributes.
service_user_hash (string):Hashed user identifier to track a specific user across services. This value will be used by the Session Ended Webhook to identify the user that is logging out.
org_user_hash:string - A string that uniquely identifies the user across the entire Organization to which the Service whose Service Key was included in the request belongs.
user_push_id (string):A value uniquely and permanently identifying the User associated with the auth_request within the Service whose Service Key was included in the request belongs. This value may be used in place of a username or directory user identifier for authorization requests.
public_key_id (string):Key ID for the public key with which the auth package was encrypted. The private key with a public key whose Key ID matches this value must be used to decrypt the auth package.

Example Response:

{
    "auth": "YXJneSBibGFyZ2hcIQo=",
    "service_user_hash": "a948904f2f0f479b8f8197694b30184b0d2ed1c1cd2a1ec0fb85d299a192a447",
    "org_user_hash": "a2eae0a42e7098d3281198601fb584f9596906c03e032a74d80df852ba837bf6",
    "user_push_id": "47f46e68-dc68-11e7-b671-0469f8dc10a5",
    "public_key_id": "d2:8e:16:91:39:5b:9d:24:73:0e:36:0a:9a:ef:7e:de"
}

Auth Package:

response (boolean):

The users response to the authorization request. true if approved and false if denied

auth_request (string):

Request-specific UUID used to match auth_request value returned from corresponding Auths POST call.

device_id (string):

Unique identifier for the device the user used to respond to the Auth Request

service_pins (string[]):

A array of strings containing of up to 5 codes separated with commas. The list is intended for for device validation in conjunction with a device_id. Devices will rotate out Service Pins as a queue, first in - first out (FIFO). protect against a myriad of potential attacks. However, they do run the risk of devices getting "out of sync" and resulting in devices not being able to authenticate.

Warning

If you implement Service Pins in your solutions, you will need to build in a recovery mechanism to reset the known app pins and re-sync the device.

Example Auth Package:

{
    "response": true,
    "auth_request": "5d1acf5c-dc5d-11e7-9ea1-0469f8dc10a5",
    "device_id": "c07c4907-dc67-11e7-bb14-0469f8dc10a5",
    "service_pins": ["6ccf814f-dc68-11e7-b379-0469f8dc10a5", "6bad9e91-dc68-11e7-aa26-0469f8dc10a5"],
}

User Contributed

LaunchKey links to user contributed code as a resource to its community. LaunchKey does not in any way guarantee or warrant the quality and security of these code bases. User contributed code is supported by the creators. If you do find a link from the site to user contributed code that is malicious or inappropriate in any way, please report that link to LaunchKey immediately and we will investigate the claim. Submit any issue to LaunchKey support at https://launchkey.com./support. ×