Auths

Path:/service/v3/auths

This endpoint provides for the 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):

The LaunchKey username or Directory User Identifier of the Directory User requiring a Session.

context (string) [optional]:

The data sent the mobile authenticator with this request.

title (string) [optional]:

The title for an individual Authorization Request from a Directory Service. This parameter will return an error if used with an Organization Service.

ttl (number) [optional]:

The custom expiration time for each individual Authorization Request. The ttl can be an integer value between 30 and 600 seconds. The default value is 300 if an expiration time is not provided.

push_title (string) [optional]:

The push title for a push notification originating from a Directory Service. By default no push title will be included. This parameter returns an error if used with an Organization Service.

push_body (string) [optional]:

The push message body for a push notification originating from a Directory Service. The default message is used unless a new body is included. This parameter returns an error if used with an Organization Service.

denial_reasons (object) [optional]:

A list array of two or more “denial reason” entries shown to an end user if the user denies the Authorization Request. This object will only display on a device that supports denial reasons as a feature. This parameter returns an error if used with an Organization Service. This parameter will also return an error if denial_context_inquiry_enabled is not set to true (see Directories).

id (string):A string mapping of 1 to 5 characters representing the reason for the denial. This value exists in an authorization response package.
reason (string):The text of the denial reason keyed to the id value and displayed to the user. Only this parameter is shown to the user.
fraud (boolean):A flag to indicate fraud as the denial reason. At least one of the items must have a fraud flag of true.

Both the id and reason attributes for a denial reason must be unique amongst the entire set of denial reasons.

policy (object) [optional]:

The 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 (array) [optional]:

A 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]:The minimum number of factors required.
knowledge (number) [optional]:Options[0, 1] - The flag determining whether a knowledge factor is required.
inherence (number) [optional]:Options[0, 1] - The flag determining whether an inherence factor is required.
possession (number) [optional]:Options[0, 1] - The flag determining whether a possession factor is required.
factors (object[]) [optional]:

An array of objects describing auth factors with the following attributes:

factor (string):

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

quickfail (boolean):

Options: [true, false] - A flag that, when true, will immediately fail the authorization upon failure of the factor causing the mobile device to not process any remaining factors.

requirement (string):

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

priority (number):

An integer value representing the priority of the factor presented to the user.

attributes (object):

An object with the following attributes:

factor enabled (number) [optional]:

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

locations (object[]) [optional]:

Required for geofence. An array 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
                        }
                    ]
                }
            }
        ]
    }
}

Example with denial_reasons:

{
"username": "my-unique-user-identifier",
"denial_reasons": [
        {"id": "b", "reason": "Bad Timing", "fraud": false},
        {"id": "a", "reason": "Absolute Fraud", "fraud": true}
                  ]
}

Response

Responses may be based on the following HTTP status codes:

200:The auth request was successfully created.
400:Invalid request. This can occur given an invalid parameter, auth policy, or when a restricted feature is being requested using an organization service. Please refer to more information on error codes via API Errors.
404:The user does not exist or the user does not have any devices.
409:Busy signal. The user already has an Authorization Request in progress. The user must either respond to this Authorization Request or the implementer can wait for the Authorization Request to timeout based on the TTL value.

Responses will be a JWE encrypted JSON payload with the following attributes.

auth_request (string):

A 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 Authorization Response Event.

error_code (string):

The particular error code associated with the response (if an error is present).

error_detail (string):

The description of the present error.

error_data (object):

A dictionary object containing the following attributes (NOTE: this object is only used if a 409 type error is present):

auth_request (string):The auth_request as described above.
from_same_service (boolean):A reference key to allow the implementer know whether the error is tied to their particular Service and whether they can attempt to resume the authentication polling for that request.
expires (string):An ISO-8601 formatted timestamp for the expires value.

Example:

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

Errors

The error_code and error_detail parameters will correspond with the error returned with the response.
Below are two examples:

Example stating that a prior Authorization Request already exist:

Currently only one pending Authorization request can exist at one time. The example below demonstrates how the response can indicate this restriction.

{
  "error_code": "SVC-005",
  "error_detail": "An auth already exists.
                   Another one cannot be created until it is either responded
                   to or expires in 250 seconds.",
  "error_data": {
    "auth_request": "adc0d351-d8a8-11e8-9fe8-acde48001122",
    "from_same_service": true,
    "expires": "2018-11-28T22:04:44Z"
  }
}

Example where Denial Context Inquiry is disabled:

If denial_context_inquiry_enabled is set to false for the Service’s parent Directory (see Service Endpoints), a
400 Invalid Request status code will be returned. The error response body will have the error_code of ARG-001 and the error_detail of Denial Context Inquiry is disabled for Services in this Directory.
{
  "error_code": "ARG-001",
  "error_detail": "denial_reasons: Denial Context Inquiry is
                    disabled for Services in this Directory."
}

GET

Get the response to an Authorization Request (if the request exists).

Request

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

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

auth_request (string):A globally unique identifier for the Authorization Request whose response is requested. This value is 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 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_jwe (string):

A JWE encrypted payload containing the user response directly from the device to the Service. As such, the LaunchKey Platform API has no knowledge of the contents of the encrypted data. The result can be decrypted using the included kid field inside of the JWE payload. auth_jwe device response should be favored over auth responses but both will be included with current mobile authenticator SDKs for the time being.

See JWE Auth Package below for its attributes.

auth (string) [DEPRECATED]:

A 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 RSA Auth Package below for its attributes.

service_user_hash (string):

A 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 where the Service belongs. The Service Key for the Service was included in the request.

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):

The 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=",
    "auth_jwe": "eyJhbGciUlNBLU9BRVAiLCA.Ppd6dIfIelfqOrj3rkw.71BJymhM-QLBQAWA.t-4rGsoXt0.1DGC4k",
    "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"
}

JWE Auth Package:

type (string):

The response type returned by the user.

reason (string):

The reason for the response type returned by the user.

auth_request (string):

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

device_id (string):

A Unique identifier tied to the device used by the user to respond to the Auth Request

service_pins (string[]):

An 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.

auth_policy (object) [optional]:

An object with the policy utilized by the device while processing the identified authorization request. This object is a result of the merging of the static Service Policy and dynamic Auth Policy if they exist.

This attribute is only received if the responding Device supports “Auth Method Insights”.

requirement (string):

This value represents the methods requirement as types, amount, or null. If types is specified, the types attribute will be included. If amount is specified, the amount attribute will be included. If null is specified, then neither types or amount will be included as neither were specified in the policy for the authorization request.

amount (number) [optional]:

The number of authentication methods required by the authorization request. Satisfying this number does not include geofences, which is dealt with separately as part of the policy for the authorization request.

types (string[]) [optional]:

The list of method types required for the authorization request. Valid values are inherence, knowledge, and possession.

geofences (object[]):

A list of applicable fences specified in the policy for the authorization request. This value will be an empty array if there are no fences.

name (string):The name of the fence. This will be null if the value was not provided.
latitude (number):The latitude of the fence.
longitude (number):The longitude of the fence.
radius (number):The size of the fence in meters.
auth_methods (object[]) [optional]:

A list of authentication method objects that describe the state of each auth method with the policy utilized by the device while processing the identified authorization request. This value is a result of the merging of the static Service Policy and dynamic Auth Policy (if they exist). The list appears in the order that the methods were processed.

This attribute is only received if the responding Device supports “Auth Method Insights”.

method (string):The authentication method identifier. It will be one of: pin_code, circle_code, geofencing, locations, wearables, fingerprint, or face.
set (boolean):Indicates if the method is set up by the user. This value will be null if not configured by the user.
active (boolean):Indicates if the method was active at the time of authorization request. This value must be true for the method to be verified during an authorization request. This value will never be null.
allowed (boolean):Indicates if the method is allowed by the mobile application implementing the Mobile Authenticator SDK. All methods that can be set can be disabled by the implementing mobile application via configuration settings in the Mobile Authenticator SDK.
supported (boolean):Indicates if the method is supported by the mobile device.
user_required (boolean):Indicates whether the user configure the method required for every authorization request.
passed (boolean):Indicates whether or not the method successfully verified. If the method was not initiated or was not able to successfully execute, the value will be null.
error (boolean):Indicates whether or not an error occurred while attempting to verify a method. If the method verification was not attempted, this value will be null.

The combination of type and reason parameters can match the following required scenarios below:

Type Reason Scenario
AUTHORIZED APPROVED User satisfies all request policy requirements; successfully authenticates with all applicable methods.
DENIED DISAPPROVED User satisfies all request policy requirements; chooses to deny request rather than proceed with authentication.
DENIED FRAUDULENT User satisfies all request policy requirements; chooses to deny request because they believe it to be fraudulent in some manner.
FAILED POLICY Authenticator fails to satisfy request policy; authentication not allowed.
FAILED PERMISSION Authenticator satisfies all request policy requirements, but permission on device prevents auth method verification.
FAILED AUTHENTICATION Authenticator satisfies all request policy requirements, but user fails to successfully authenticate with all required authentication methods.
FAILED CONFIGURATION Authenticator fails to satisfy request policy because authenticator configuration is incompatible with the request policy(i.e. requiring an auth method that is configured to be unavailable to end users).
FAILED BUSY_LOCAL User can’t receive or respond to request because a Local Auth Request is pending authorization.

Below are three Example decrypted JWE Auth Packages:

Authorization Success:

{
    "type": "AUTHORIZED",
    "reason": "APPROVED",
    "device_id": "c07c4907-dc67-11e7-bb14-0469f8dc10a5",
    "service_pins": ["2648", "2046", "0583", "2963", "2046"],
    "auth_request": "5d1acf5c-dc5d-11e7-9ea1-0469f8dc10a5"
}

Fraudulent Denial:

{
    "type": "DENIED",
    "reason": "FRAUDULENT",
    "denial_reason": "DEN2",
    "device_id": "c07c4907-dc67-11e7-bb14-0469f8dc10a5",
    "service_pins": ["2648", "2046", "0583", "2963", "2046"],
    "auth_request": "5d1acf5c-dc5d-11e7-9ea1-0469f8dc10a5",
    "auth_policy": {
        "requirement": null,
        "geofences": [ ]
    },
    "auth_methods": [
        {
          "method": "wearable",
          "set": false,
          "active": false,
          "allowed": true,
          "supported": true,
          "user_required": null,
          "passed": null,
          "error": null
        },
        {
          "method": "geofencing",
          "set": null,
          "active": true,
          "allowed": true,
          "supported": true,
          "user_required": null,
          "passed": null,
          "error": null
        },
        {
          "method": "locations",
          "set": true,
          "active": true,
          "allowed": true,
          "supported": true,
          "user_required": true,
          "passed": null,
          "error": null
        },
       {
          "method": "pin_code",
          "set": true,
          "active": true,
          "allowed": true,
          "supported": true,
          "user_required": true,
          "passed": null,
          "error": null
        },
        {
          "method": "circle_code",
          "set": false,
          "active": false,
          "allowed": true,
          "supported": true,
          "user_required": null,
          "passed": null,
          "error": null
        },
        {
          "method": "face",
          "set": false,
          "active": false,
          "allowed": true,
          "supported": true,
          "user_required": null,
          "passed": null,
          "error": null
        },
        {
          "method": "fingerprint",
          "set": false,
          "active": false,
          "allowed": true,
          "supported": true,
          "user_required": null,
          "passed": null,
          "error": null
        }
    ]
}

Configuration Failure:

The auth_policy requires a possession method. The only possession method available is wearable

{
    "type": "FAILED",
    "reason": "CONFIGURATION",
    "device_id": "c07c4907-dc67-11e7-bb14-0469f8dc10a5",
    "service_pins": ["2648", "2046", "0583", "2963", "2046"],
    "auth_request": "5d1acf5c-dc5d-11e7-9ea1-0469f8dc10a5"
    "auth_policy": {
        "requirement": "types",
        "types": ["possession"]
        "geofences": []
    },
    "auth_methods": [
        {
          "method": "wearable",
          "set": null,
          "active": false,
          "allowed": false,
          "supported": true,
          "user_required": null,
          "passed": null,
          "error": null
        },
        {
          "method": "geofencing",
          "set": null,
          "active": true,
          "allowed": true,
          "supported": true,
          "user_required": null,
          "passed": null,
          "error": null
        },
        {
          "method": "locations",
          "set": false,
          "active": false,
          "allowed": true,
          "supported": true,
          "user_required": false,
          "passed": null,
          "error": null
        },
       {
          "method": "pin_code",
          "set": false,
          "active": false,
          "allowed": true,
          "supported": true,
          "user_required": false,
          "passed": null,
          "error": null
        },
        {
          "method": "circle_code",
          "set": false,
          "active": false,
          "allowed": true,
          "supported": true,
          "user_required": null,
          "passed": null,
          "error": null
        },
        {
          "method": "face",
          "set": false,
          "active": false,
          "allowed": true,
          "supported": true,
          "user_required": null,
          "passed": null,
          "error": null
        },
        {
          "method": "fingerprint",
          "set": false,
          "active": false,
          "allowed": true,
          "supported": true,
          "user_required": null,
          "passed": null,
          "error": null
        }
    ]
}

RSA Auth Package (DEPRECATED):

response (string):

The users response to the Authorization Request. true if approved and false if denied

auth_request (string):

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

device_id (string):

A Unique identifier tied to the device used by the user to respond to the Auth Request

service_pins (string[]):

An 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 decrypted RSA 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"
                    ]
}

DELETE

Cancel an Authorization Request for the Service.

Request

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

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

auth_request (string):A globally unique identifier for the Authorization Request whose response is requested. This value is received via a POST call.

Example:

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

Response

There is no response data, but responses may be based on the following HTTP status codes:

204:The auth request was successfully canceled.
400:Invalid request. This can occur given an invalid parameter or when the auth itself cannot be canceled. Please refer to more information on error codes via API Errors.
404:The auth request either does not exist or was expired.

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. ×