1. Overview

The Encap REST API is used to integrate client systems with the Encap server in order to perform mobile authentication of customers via designated mobile applications that integrate the Encap mobile authentication API.

Operations provided via the API are currently divided into the following categories:

  1. Enrollment: Operations facilitating the enrollment of a supported application instance on a customer’s mobile device with the Encap server. The enrollment process creates a very strong cryptographic binding between the device/application instance and the server which can then be used to perform authentication operations.

  2. Authentication: Operations for executing secure mobile authentication requests via previously-enrolled device/application instances.

  3. Device Management: Operations for the management of enrolled device/application instances, including locking/unlocking of instances and deactivation/un-enrollment.

  4. Admin APIs: Administrative checks and operations.

2. Common concepts

2.1. REST API authentication

Authentication for REST API calls (not to confuse with the authentication service itself) are handled by using Basic Authentication. All requests are required to have an Authorization header containing a Basic Authentication string. The Basic Authentication should have the API key id as username and the API key secret as password. API key provisioning is handled by the Encap server administrator.

GET /api/smart-device/v1/authentications/fdec332b-5525-4d03-b8e1-abfdcd91785e HTTP/1.1
Authorization: Basic N2QyMTEzMGYtZGE1MC00Yzk1LWFkOTktZmJjZjg1OGQ0MGNmOllZZjZLSGtxNzhjVXduZkQ4NkdmbUE9PQ==
Host: localhost:8080

2.1.1. Authentication error response

During authentication there are two errors that can occur

400 Bad Request is returned if the request is missing the required authentication headers.

401 Unauthorized is returned when authentication fails due to wrong/invalid API key id or API key secret.

2.2. HTTP verbs

The API is implemented to adhere as closely as possible to HTTP standard and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource.

POST

Used to create a new resource.

PUT

Full update of an existing resource.

PATCH

Partial update of an existing resource.

DELETE

Used to delete an existing resource.

2.3. HTTP status codes

The API is implemented to adhere as closely as possible to HTTP standard and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

The request completed successfully

201 Created

A new resource has been created successfully. The resource’s URI is available from the response’s Location header

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

The request was malformed. The response body will include an error providing further information.

401 Unauthorized

Authentication/Authorization failed for the request

403 Forbidden

Client not authorized to access the operation on the specified resource

404 Not Found

Resource with the given id does not exist

409 Conflict

Tried to create a resource that already exists

412 Precondition Failed

Conditional request, but conditions not fulfilled

422 Unprocessable Entity

Content well formed but content validation failed

428 Precondition Required

Conditional request required but no condition given

500 Internal Server Error

Unexpected failure on server side

2.4. Errors

The API uses HTTP status codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the request data provided (e.g., a required parameter was omitted, a device state not appropriate, etc.), and codes in the 5xx range indicate an error with the API servers.

Not all errors map cleanly onto HTTP response codes. Some 4xx codes also contain an error entity in the response explaining the error in more detail. In very rare cases HTTP 500 will do the same.

2.4.1. The error object

The error entity has the following response structure:

Field Type Description

status

Number

Holds a duplicate copy of the HTTP error status code for convenience, so that clients can “see” it without having to analyze the response’s header

code

String

Unique code for this specific error type. More fine grained than the HTTP code, e.g. "AUTH_LEVEL_NOT_AVAILABLE_FOR_DEVICE"

message

String

Short description of the error, what might have cause it and possibly a “fixing” proposal, e.g. "Device is not activated for 2FA authentication, activate the device for 2FA before trying to use it for 2FA authentication"

correlation_id

String

The correlation ID sent in the request or generated on the server. Will contain the same value as the response header X-Correlation-UUID. Can be used to find the correlating error messages from the server log

developer_message

String

Detailed message, containing additional data that might be relevant to the developer. Only provided when development mode is switched on and can potentially contain stack trace information or similar

errors

Array

Array of field specific errors if there are any, typically used for validation faults (HTTP 422)

Field specific error

Field Type Description

field

String

Field name if the error is related to a specific field

code

String

Specific code for the error situation, e.g. "FIELD_TO_LONG"

message

String

Human readable description of the error code, e.g. "Field allows max 255 characters"

2.4.2. Error codes

Error code Description

REST_UNEXPECTED

An unexpected error occurred

REST_VALIDATION_FAULT

Validation of request failed

REST_RESOURCE_NOT_FOUND

Resource does not exist

REST_RESOURCE_ALREADY_EXISTS

Resource already exists

REST_PAGINATION_OFFSET_NOT_FOUND

Provided offset id does not exist

REST_HTTP_MESSAGE_NOT_READABLE

Server was not able to parse the request

REST_UNSUPPORTED_MEDIA_TYPE

Provided media type is not supported, server supports application/json

REST_NOT_ACCEPTABLE

Server does not accept the request

REST_UNAUTHORIZED

Request is unauthorized

REST_NOT_REGISTERED

Device is not registered

REST_SESSION_EXPIRY_TIME_EXCEEDS_MAX

Provided session expiry time exceeds the maximum allowed value

REST_TOO_MANY_ACTIVATION_SESSIONS_IN_PROGRESS

Too many concurrent active activation sessions

REST_ACTIVATION_CODE_CREATION_FAILED

Server failed to create activation code

REST_NO_ACTIVE_SESSION

No active sessions found for the device

REST_REGISTRATION_IS_LOCKED

Device is locked. See device API for details

REST_REGISTRATION_NOT_LOCKED

Device is not locked

REST_NOT_AN_ACTIVATION_SESSION

Provided session is not an activation session

REST_AUTH_LEVEL_NOT_ALLOWED

Authentication level is not allowed

REST_AUTH_METHOD_NOT_ALLOWED

Authentication method is not configured for this app config

REST_AUTH_METHOD_AND_AUTH_LEVEL_MISMATCH

Authentication method and level does not match each other

REST_AUTH_METHOD_NOT_ACTIVATED_FOR_REGISTRATION

Authentication method is not activated for the device

REST_NOT_AN_AUTHENTICATION_SESSION

Provided session is not an authentication session

REST_NOT_AN_OFFLINE_AUTHENTICATION_SESSION

Provided session is not an offline authentication session

REST_UNSUPPORTED_PURPOSE_ON_SESSION

The purpose of the provided session is not supported

REST_APP_CONFIG_INVALID

The application configuration provided is not valid.

REST_APPLICATION_ID_NOT_FOUND

The application ID was not found.

REST_APNS_KEY_IN_USE

The APNS key is used by one or more application configurations

REST_KEY_IN_USE

The End-to-End key has status ENABLED and is considered in use

REST_PATCH_OBJECT_MAPPING_FAILED

The patch request is not of a valid format and cannot be mapped to the object that is supposed to be updated.

REST_PUSH_CONFIGURATION_ERROR

Authentication request has sendPush flag set to true, but nativePushEnabled option in app configuration is false.

REST_SESSION_EXPIRED

The session has expired and can no longer be used

REST_SESSION_CONSUMED

The session has already had a failed or successful outcome

REST_SESSION_CANCELLED

The session is cancelled and can no longer be used

REST_AUTH_METHOD_LOCKED

The specified authentication method is locked. If the method in question is an offline-method, other methods might still work.

REST_AUTH_METHOD_NOT_LOCKED

The authentication method you are trying to unlock is not locked

REST_AUTH_METHOD_REQUIRED

Authentication method is required in the request

REST_MISSING_REQUEST_PARAMETER

The request is missing one or more request parameters

REST_NOT_A_PERFORM_RECOVERY_SESSION

The purpose of the given session is not perform recovery.

REST_DEVICE_ID_LIMIT_EXCEEDED

Too many device IDs were passed when listing sessions for devices; the number of devices is limited to 100.
Example request

A request that triggers a validation error will produce a 422 Unprocessable Entity response:

HTTP/1.1 422 Unprocessable Entity
X-Correlation-UUID: 72a4b514-41d7-49a0-9eaa-67a9f0ae6f1d
Content-Type: application/json
Content-Length: 15821

{
  "status" : 422,
  "code" : "REST_VALIDATION_FAULT",
  "message" : "Parameter validation failed on request /smart-device/v1/devices/d35a4e54-012d-4330-88b0-b8472f4a39ea/sessions. For more information see field specific errors.",
  "developer_message" : "Validation failed for argument [2] in org.springframework.http.ResponseEntity<com.encapsecurity.encap.rest.api.dto.PaginationResponseDTO<com.encapsecurity.encap.rest.api.dto.DeviceSessionDetailsDTO>> com.encapsecurity.encap.rest.controller.DeviceController.getSessionsForDevice(com.encapsecurity.encap.domain.EncapPrincipal,java.util.UUID,com.encapsecurity.encap.rest.api.dto.PaginationRequestDTO) with 2 errors: [Field error in object 'paginationRequestDTO' on field 'limit': rejected value [pp]; codes [typeMismatch.paginationRequestDTO.limit,typeMismatch.limit,typeMismatch.int,typeMismatch]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [paginationRequestDTO.limit,limit]; arguments []; default message [limit]]; default message [Failed to convert property value of type 'java.lang.String' to required type 'int' for property 'limit'; For input string: \"pp\"]] [Field error in object 'paginationRequestDTO' on field 'offset': rejected value [ll]; codes [typeMismatch.paginationRequestDTO.offset,typeMismatch.offset,typeMismatch.java.util.UUID,typeMismatch]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [paginationRequestDTO.offset,offset]; arguments []; default message [offset]]; default message [Failed to convert property value of type 'java.lang.String' to required type 'java.util.UUID' for property 'offset'; Invalid UUID string: ll]] \norg.springframework.web.bind.MethodArgumentNotValidException: Validation failed for argument [2] in org.springframework.http.ResponseEntity<com.encapsecurity.encap.rest.api.dto.PaginationResponseDTO<com.encapsecurity.encap.rest.api.dto.DeviceSessionDetailsDTO>> com.encapsecurity.encap.rest.controller.DeviceController.getSessionsForDevice(com.encapsecurity.encap.domain.EncapPrincipal,java.util.UUID,com.encapsecurity.encap.rest.api.dto.PaginationRequestDTO) with 2 errors: [Field error in object 'paginationRequestDTO' on field 'limit': rejected value [pp]; codes [typeMismatch.paginationRequestDTO.limit,typeMismatch.limit,typeMismatch.int,typeMismatch]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [paginationRequestDTO.limit,limit]; arguments []; default message [limit]]; default message [Failed to convert property value of type 'java.lang.String' to required type 'int' for property 'limit'; For input string: \"pp\"]] [Field error in object 'paginationRequestDTO' on field 'offset': rejected value [ll]; codes [typeMismatch.paginationRequestDTO.offset,typeMismatch.offset,typeMismatch.java.util.UUID,typeMismatch]; arguments [org.springframework.context.support.DefaultMessageSourceResolvable: codes [paginationRequestDTO.offset,offset]; arguments []; default message [offset]]; default message [Failed to convert property value of type 'java.lang.String' to required type 'java.util.UUID' for property 'offset'; Invalid UUID string: ll]] \n\tat org.springframework.web.method.annotation.ModelAttributeMethodProcessor.resolveArgument(ModelAttributeMethodProcessor.java:177)\n\tat org.springframework.web.method.support.HandlerMethodArgumentResolverComposite.resolveArgument(HandlerMethodArgumentResolverComposite.java:122)\n\tat org.springframework.web.method.support.InvocableHandlerMethod.getMethodArgumentValues(InvocableHandlerMethod.java:181)\n\tat org.springframework.web.method.support.InvocableHandlerMethod.invokeForRequest(InvocableHandlerMethod.java:148)\n\tat org.springframework.web.servlet.mvc.method.annotation.ServletInvocableHandlerMethod.invokeAndHandle(ServletInvocableHandlerMethod.java:118)\n\tat org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.invokeHandlerMethod(RequestMappingHandlerAdapter.java:884)\n\tat org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.handleInternal(RequestMappingHandlerAdapter.java:797)\n\tat org.springframework.web.servlet.mvc.method.AbstractHandlerMethodAdapter.handle(AbstractHandlerMethodAdapter.java:87)\n\tat org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1081)\n\tat org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:974)\n\tat org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1011)\n\tat org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:903)\n\tat jakarta.servlet.http.HttpServlet.service(HttpServlet.java:527)\n\tat org.springframework.web.servlet.FrameworkServlet.service(FrameworkServlet.java:885)\n\tat org.springframework.test.web.servlet.TestDispatcherServlet.service(TestDispatcherServlet.java:72)\n\tat jakarta.servlet.http.HttpServlet.service(HttpServlet.java:614)\n\tat org.springframework.mock.web.MockFilterChain$ServletFilterProxy.doFilter(MockFilterChain.java:165)\n\tat org.springframework.mock.web.MockFilterChain.doFilter(MockFilterChain.java:132)\n\tat com.encapsecurity.encap.rest.filter.BasicAuthenticationFilter.doFilterInternal(BasicAuthenticationFilter.java:89)\n\tat org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)\n\tat org.springframework.mock.web.MockFilterChain.doFilter(MockFilterChain.java:132)\n\tat com.encapsecurity.encap.rest.filter.RequestCorrelationIdFilter.doFilterInternal(RequestCorrelationIdFilter.java:22)\n\tat org.springframework.web.filter.OncePerRequestFilter.doFilter(OncePerRequestFilter.java:116)\n\tat org.springframework.mock.web.MockFilterChain.doFilter(MockFilterChain.java:132)\n\tat com.encapsecurity.encap.config.filter.AuditContextFilter.doFilter(AuditContextFilter.java:64)\n\tat org.springframework.mock.web.MockFilterChain.doFilter(MockFilterChain.java:132)\n\tat org.springframework.test.web.servlet.MockMvc.perform(MockMvc.java:201)\n\tat com.encapsecurity.encap.rest.controller.ExceptionThrowingControllerTest.typeMismatchOnPaginationRequestParam(ExceptionThrowingControllerTest.java:111)\n\tat java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)\n\tat java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)\n\tat java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)\n\tat java.base/java.lang.reflect.Method.invoke(Unknown Source)\n\tat org.junit.platform.commons.util.ReflectionUtils.invokeMethod(ReflectionUtils.java:727)\n\tat org.junit.jupiter.engine.execution.MethodInvocation.proceed(MethodInvocation.java:60)\n\tat org.junit.jupiter.engine.execution.InvocationInterceptorChain$ValidatingInvocation.proceed(InvocationInterceptorChain.java:131)\n\tat org.junit.jupiter.engine.extension.TimeoutExtension.intercept(TimeoutExtension.java:156)\n\tat org.junit.jupiter.engine.extension.TimeoutExtension.interceptTestableMethod(TimeoutExtension.java:147)\n\tat org.junit.jupiter.engine.extension.TimeoutExtension.interceptTestMethod(TimeoutExtension.java:86)\n\tat org.junit.jupiter.engine.execution.InterceptingExecutableInvoker$ReflectiveInterceptorCall.lambda$ofVoidMethod$0(InterceptingExecutableInvoker.java:103)\n\tat org.junit.jupiter.engine.execution.InterceptingExecutableInvoker.lambda$invoke$0(InterceptingExecutableInvoker.java:93)\n\tat org.junit.jupiter.engine.execution.InvocationInterceptorChain$InterceptedInvocation.proceed(InvocationInterceptorChain.java:106)\n\tat org.junit.jupiter.engine.execution.InvocationInterceptorChain.proceed(InvocationInterceptorChain.java:64)\n\tat org.junit.jupiter.engine.execution.InvocationInterceptorChain.chainAndInvoke(InvocationInterceptorChain.java:45)\n\tat org.junit.jupiter.engine.execution.InvocationInterceptorChain.invoke(InvocationInterceptorChain.java:37)\n\tat org.junit.jupiter.engine.execution.InterceptingExecutableInvoker.invoke(InterceptingExecutableInvoker.java:92)\n\tat org.junit.jupiter.engine.execution.InterceptingExecutableInvoker.invoke(InterceptingExecutableInvoker.java:86)\n\tat org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.lambda$invokeTestMethod$7(TestMethodTestDescriptor.java:217)\n\tat org.junit.platform.engine.support.hierarchical.ThrowableCollector.execute(ThrowableCollector.java:73)\n\tat org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.invokeTestMethod(TestMethodTestDescriptor.java:213)\n\tat org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.execute(TestMethodTestDescriptor.java:138)\n\tat org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.execute(TestMethodTestDescriptor.java:68)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$6(NodeTestTask.java:151)\n\tat org.junit.platform.engine.support.hierarchical.ThrowableCollector.execute(ThrowableCollector.java:73)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$8(NodeTestTask.java:141)\n\tat org.junit.platform.engine.support.hierarchical.Node.around(Node.java:137)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$9(NodeTestTask.java:139)\n\tat org.junit.platform.engine.support.hierarchical.ThrowableCollector.execute(ThrowableCollector.java:73)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.executeRecursively(NodeTestTask.java:138)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.execute(NodeTestTask.java:95)\n\tat java.base/java.util.ArrayList.forEach(Unknown Source)\n\tat org.junit.platform.engine.support.hierarchical.SameThreadHierarchicalTestExecutorService.invokeAll(SameThreadHierarchicalTestExecutorService.java:41)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$6(NodeTestTask.java:155)\n\tat org.junit.platform.engine.support.hierarchical.ThrowableCollector.execute(ThrowableCollector.java:73)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$8(NodeTestTask.java:141)\n\tat org.junit.platform.engine.support.hierarchical.Node.around(Node.java:137)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$9(NodeTestTask.java:139)\n\tat org.junit.platform.engine.support.hierarchical.ThrowableCollector.execute(ThrowableCollector.java:73)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.executeRecursively(NodeTestTask.java:138)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.execute(NodeTestTask.java:95)\n\tat java.base/java.util.ArrayList.forEach(Unknown Source)\n\tat org.junit.platform.engine.support.hierarchical.SameThreadHierarchicalTestExecutorService.invokeAll(SameThreadHierarchicalTestExecutorService.java:41)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$6(NodeTestTask.java:155)\n\tat org.junit.platform.engine.support.hierarchical.ThrowableCollector.execute(ThrowableCollector.java:73)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$8(NodeTestTask.java:141)\n\tat org.junit.platform.engine.support.hierarchical.Node.around(Node.java:137)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$9(NodeTestTask.java:139)\n\tat org.junit.platform.engine.support.hierarchical.ThrowableCollector.execute(ThrowableCollector.java:73)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.executeRecursively(NodeTestTask.java:138)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.execute(NodeTestTask.java:95)\n\tat org.junit.platform.engine.support.hierarchical.SameThreadHierarchicalTestExecutorService.submit(SameThreadHierarchicalTestExecutorService.java:35)\n\tat org.junit.platform.engine.support.hierarchical.HierarchicalTestExecutor.execute(HierarchicalTestExecutor.java:57)\n\tat org.junit.platform.engine.support.hierarchical.HierarchicalTestEngine.execute(HierarchicalTestEngine.java:54)\n\tat org.junit.platform.launcher.core.EngineExecutionOrchestrator.execute(EngineExecutionOrchestrator.java:107)\n\tat org.junit.platform.launcher.core.EngineExecutionOrchestrator.execute(EngineExecutionOrchestrator.java:88)\n\tat org.junit.platform.launcher.core.EngineExecutionOrchestrator.lambda$execute$0(EngineExecutionOrchestrator.java:54)\n\tat org.junit.platform.launcher.core.EngineExecutionOrchestrator.withInterceptedStreams(EngineExecutionOrchestrator.java:67)\n\tat org.junit.platform.launcher.core.EngineExecutionOrchestrator.execute(EngineExecutionOrchestrator.java:52)\n\tat org.junit.platform.launcher.core.DefaultLauncher.execute(DefaultLauncher.java:114)\n\tat org.junit.platform.launcher.core.DefaultLauncher.execute(DefaultLauncher.java:86)\n\tat org.junit.platform.launcher.core.DefaultLauncherSession$DelegatingLauncher.execute(DefaultLauncherSession.java:86)\n\tat org.gradle.api.internal.tasks.testing.junitplatform.JUnitPlatformTestClassProcessor$CollectAllTestClassesExecutor.processAllTestClasses(JUnitPlatformTestClassProcessor.java:118)\n\tat org.gradle.api.internal.tasks.testing.junitplatform.JUnitPlatformTestClassProcessor$CollectAllTestClassesExecutor.access$000(JUnitPlatformTestClassProcessor.java:93)\n\tat org.gradle.api.internal.tasks.testing.junitplatform.JUnitPlatformTestClassProcessor.stop(JUnitPlatformTestClassProcessor.java:88)\n\tat org.gradle.api.internal.tasks.testing.SuiteTestClassProcessor.stop(SuiteTestClassProcessor.java:62)\n\tat java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)\n\tat java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)\n\tat java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)\n\tat java.base/java.lang.reflect.Method.invoke(Unknown Source)\n\tat org.gradle.internal.dispatch.ReflectionDispatch.dispatch(ReflectionDispatch.java:36)\n\tat org.gradle.internal.dispatch.ReflectionDispatch.dispatch(ReflectionDispatch.java:24)\n\tat org.gradle.internal.dispatch.ContextClassLoaderDispatch.dispatch(ContextClassLoaderDispatch.java:33)\n\tat org.gradle.internal.dispatch.ProxyDispatchAdapter$DispatchingInvocationHandler.invoke(ProxyDispatchAdapter.java:94)\n\tat jdk.proxy2/jdk.proxy2.$Proxy5.stop(Unknown Source)\n\tat org.gradle.api.internal.tasks.testing.worker.TestWorker$3.run(TestWorker.java:193)\n\tat org.gradle.api.internal.tasks.testing.worker.TestWorker.executeAndMaintainThreadName(TestWorker.java:129)\n\tat org.gradle.api.internal.tasks.testing.worker.TestWorker.execute(TestWorker.java:100)\n\tat org.gradle.api.internal.tasks.testing.worker.TestWorker.execute(TestWorker.java:60)\n\tat org.gradle.process.internal.worker.child.ActionExecutionWorker.execute(ActionExecutionWorker.java:56)\n\tat org.gradle.process.internal.worker.child.SystemApplicationClassLoaderWorker.call(SystemApplicationClassLoaderWorker.java:113)\n\tat org.gradle.process.internal.worker.child.SystemApplicationClassLoaderWorker.call(SystemApplicationClassLoaderWorker.java:65)\n\tat worker.org.gradle.process.internal.worker.GradleWorkerMain.run(GradleWorkerMain.java:69)\n\tat worker.org.gradle.process.internal.worker.GradleWorkerMain.main(GradleWorkerMain.java:74)\n",
  "correlation_id" : "72a4b514-41d7-49a0-9eaa-67a9f0ae6f1d",
  "errors" : [ {
    "field" : "limit",
    "code" : "REST_TYPE_MISMATCH",
    "message" : "Failed to convert property value of type 'java.lang.String' to required type 'int' for property 'limit'; For input string: \"pp\""
  }, {
    "field" : "offset",
    "code" : "REST_TYPE_MISMATCH",
    "message" : "Failed to convert property value of type 'java.lang.String' to required type 'java.util.UUID' for property 'offset'; Invalid UUID string: ll"
  } ]
}

2.5. Headers

2.5.1. Request header

Name Description

X-Correlation-UUID

Optional request header with a UUID for the request, if not present the server will generate a UUID. If the provided UUID is invalid server will respond with HTTP code 400

Authorization

Authentication is performed via HTTP Basic Auth, and an API key is provided as the basic auth username value and the API secret as the password value, username and password is expected to be separated with a ':'. This header is required.

2.5.2. Response header

Every response has the following header(s):

Name Description

X-Correlation-UUID

A UUID for the request. Id can be provided in the request header, if not provided it will be generated by the server

2.6. Pagination

All Encap REST APIs that returns a collection of data supports pagination.

2.6.1. Request

Pagination requests has the following request parameters:

Parameter Description

offset

Id of the first session to include in response. Offset is optional, if not provided the result will start with the first session in the device history

limit

The number of objects on each page. Limit is optional, if not provided the defualt of 100 will be used.

2.6.2. Response

Pagination response has the following structure:

Field Type Description

previous

String

Holds the url to the previous set of items

next

String

Holds the url to the next set of items

offset

String

Offset as passed in request

limit

Number

The number of items on each page

items

Array

Items contains a list of the paginated objects for the request

Example of pagination response:

HTTP/1.1 200 OK
X-Correlation-UUID: 627655de-ae88-4e4b-9ccf-0f7cc3289e33
Content-Type: application/json
Content-Length: 1541

{
  "previous" : "/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/sessions?limit=3&offset=e26f89f6-e921-42eb-b1d8-ac5c1d2201dd",
  "next" : "/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/sessions?limit=3&offset=1f73d6d7-b3a4-460c-87fe-3fa7ef5d661e",
  "offset" : "e3fd27f7-57c3-4c46-b0f1-f3fa14cc02dd",
  "limit" : 3,
  "items" : [ {
    "session_id" : "608f267f-3b30-4c70-81ec-c27c9b848c1b",
    "device_id" : "79735c4b-5def-43f3-9e60-3edc5a3d75ae",
    "ref" : "/enrollments/608f267f-3b30-4c70-81ec-c27c9b848c1b",
    "purpose" : "ACTIVATION",
    "state" : "SUCCESS",
    "client_only" : false,
    "session_created_on" : "2023-09-28T11:29:37.801UTC",
    "session_expires_on" : "2023-09-28T11:29:37.801UTC",
    "offline" : false
  }, {
    "session_id" : "513023a1-4a9e-4589-a0d7-ebd3f42b0b9d",
    "device_id" : "79735c4b-5def-43f3-9e60-3edc5a3d75ae",
    "ref" : "/authentications/513023a1-4a9e-4589-a0d7-ebd3f42b0b9d",
    "purpose" : "AUTHENTICATION",
    "state" : "IN_PROGRESS",
    "client_only" : false,
    "session_created_on" : "2023-09-28T11:29:37.801UTC",
    "session_expires_on" : "2023-09-28T11:29:37.801UTC",
    "offline" : false
  }, {
    "session_id" : "b547848f-e47b-4ca3-834c-af1968c4dd3e",
    "device_id" : "79735c4b-5def-43f3-9e60-3edc5a3d75ae",
    "purpose" : "DELETE_RECOVERY",
    "state" : "IN_PROGRESS",
    "client_only" : false,
    "session_created_on" : "2023-09-28T11:29:37.801UTC",
    "session_expires_on" : "2023-09-28T11:29:37.801UTC",
    "offline" : false
  } ]
}

3. Smart Device API

3.1. Common objects

3.1.1. The risk attributes object

Field Type Description

name

String

The name of the risk attribute

value

String

The value of the risk attribute
Risk attributes

Encap can collect a set af risk attributes for each operation, what attributes to collect is configured in the application configuration

Risk attribute Config attribute Type Since Description

operating_system_fingerprint

Fingerprint

String

A fingerprint of the operating system. This can be used for detecting whether the device is running a custom ROM or operating system

operating_system_version

SystemVersion

String

The operating system version. Examples: 4.1.2, 6.0.1

input_method

InputMethod

String

The input method that was used to enter text in the application. Can be used to detect when a custom keyboard is used on the device.

For more info on input methods please see: https://developer.android.com/guide/topics/text/creating-input-method

is_debuggable

IsDebuggable

Boolean

Indicate whether the application running can be debugged using a source level debugger, either by manifest entry or in emulator

is_debug_enabled

IsDebugEnabled

Boolean

Indicate whether debug is enabled on device, either by user setting (USB-debugging enabled) or when running in emulator (debugging enabled by default)

is_debugger_connected

IsDebuggerConnected

Boolean

Indicate whether a debugger is connected to the application

is_emulator

IsEmulator

Boolean

Indicate whether the application is running in an emulator

is_root_available

IsRootAvailable

Boolean

Indicate whether the device has been rooted/jail-broken.

For iOS this value has to be passed to Encap using the setRiskParameter API. If the application is using Shield the callback value can be passed to Encap.

is_secure_screen_lock_enabled

IsSecureScreenLockEnabled

Boolean

3.5

Indicate whether the device has secure screen enabled or not

is_unknown_sources_enabled

IsUnknownSourcesEnabled

Boolean

Indicate whether the device allows installation of applications outside the application store

server_client_ip

SeverClientIp

String

3.5

The host address the request originated from. It will contain the value of X-Forwarded-For (XFF) header from the request and can contain multiple IP addresses depending on proxy and load balancers.

If XFF is not present we will use the remote address of the request. It can be either the IP of the client or the last proxy that sent the request, it is specified by the value of the Common Gateway Interface (CGI) variable REMOTE_ADDR.

signer_hashes

SignerHashes

Base64

A SHA-256 hash of the public key of certificate of the application signer. If there are more signers, each hash is comma separated. This can be used for detecting whether the application has been re-signed.

user_agent

UserAgent

String

HTTP User agent from smart device application.

device_hash

DeviceHash

Base64

SHA256 hash of the unique hardware device ID of the client device.

device_manufacturer

DeviceManufacturer

String

The manufacturer of the device. Examples: "Apple", "Samsung".

device_model

DeviceModel

String

The device’s model. Examples: "iPad2,2", "Nexus S".

operating_system_type

OperatingSystemType

String

Indicates the OperatingSystemType of the device, either Android or iOS.

application_hash

ApplicationHash

Base64

SHA256 hash of the application name. The server can use this for detecting re-packaging.

client_side_ip

NetworkInterfaces

JSON

3.6

An array containing the client network interfaces. This includes the type of the network and the IP address, and the list can contain multiple interfaces if the user’s device is connected to more than one at the time of the transaction.

Example: [{"Type":"Cellular","IPAddress":"123.123.123.123"},{"Type":"Wifi","IPAddress":"124.124.124.124"}]

hw_key_client_status

HwKeyClientStatus

String

3.8

The status of the hardware protected key signature preformed by the Encap client SDK.

hw_key_server_result

HwKeyServerResult

String

3.8

The result of the hardware protected key signature verification on the Encap server.

battery_level

BatteryLevel

Integer

3.12

Provide battery level of the device.

is_power_connected

IsPowerConnected

Boolean

3.12

Indicate whether the device is being charged/connected to a charger.

location

Location

Object

Location data from the device. The response is part of the location object, and is not included as values in the risk attribute object.
Hardware protected key server result

These are the possible values for the hw_key_server_result attribute.

Status Description Validation strategy

SIGNATURE_VERIFICATION_SUCCESS

Verification of the hardware protected key signature was successful

Operation is successful in both strategy modes.

SIGNATURE_VERIFICATION_FAILED

Verification of the hardware protected key signature failed.

Operation will fail in SUPPORTED mode.

NOT_ACTIVATED_WITH_HW_KEY

Signature could not be verified because registration was not activated with hardware protected keys. Only applicable for authentication.

Operation will not fail regardless of strategy mode.

NOT_PROVIDED_BY_CLIENT

The client is on an Encap version that does not support the hardware protected key feature. Only applicable for enrollment.

Operation will not fail regardless of strategy mode.

The device will be activated without hardware protected keys, and the device will be able to perform all operations but will not be able to use the hardware protected key feature. To enable this feature the client must enroll on Encap version 3.8 or newer.
Hardware protected key client statuses

These are the possible values for the hw_key_client_status attribute.

Status Description Operation

OK_KEY_PROVIDED

Activation of hardware protected keys was successful on the client.

Enrollment

OK_SIGNED_SUCCESS

Authentication challenge was successfully signed with the hardware protected key on the client.

Authentication

INFO_NO_HARDWARE_SUPPORT

The client device does not have Secure Enclave, or it is running in a simulator. Only for iOS

Enrollment

INFO_NO_OPERATING_SYSTEM_SUPPORT

The client operating system does not support hardware backed keys.

It is supported on:

  • Android 6 (most devices)

  • Android 7 or later (all devices)

  • iOS 10 or later (devices with Secure Enclave)

Enrollment

INFO_NOT_ACTIVATED_WITH_HW_KEY

The registration was not activated with hardware protected keys support for one or more of the following reasons:

  • Encap API did not support hardware crypto protected keys

  • Device Operating System did not support hardware crypto protected keys

  • Device Hardware does not support hardware crypto protected keys

Authentication

ERR_KEY_GENERATION_FAILED

Unexpected error during generation of keypair on client.

Enrollment

ERR_RETRIEVE_PUBLIC_KEY_FAILED

Unexpected error retrieving public key. Only on iOS.

Enrollment

ERR_RETRIEVE_PRIVATE_KEY_REF_FAILED

Unexpected error when retrieving reference to private key.

Enrollment and Authentication

ERR_SIGN_OPERATION_FAILED

Unexpected error when generating signature.

Enrollment and Authentication

3.1.2. The location object

Encap can collect the location of the device for each operation, given that it is enabled in the application configuration. This requires the end user to give the application permission to use the location of the device.

Field Type Description

accuracy

String

Location accuracy

altitude

String

Location altitude

latitude

String

Location latitude

longitude

String

Location longitude

3.1.3. The operation context object

Field Type Description

context_title_b64

String

Context title, that is base64 encoded twice. The double base64 encoding is a bug, the documentation will be updated once it’s fixed

context_content_b64

String

Context content, that is base64 encoded twice. The double base64 encoding is a bug, the documentation will be updated once it’s fixed

context_mime

String

The MIME type of the content

3.1.4. The session status object

Field Type Description

status

String

The status of the session. See session status for details.

description

String

A description of the session status

state

String

The state of the session. See session state for details.
Session statuses
Session Status Description

IN_PROGRESS

Operation is in progress

AUTHENTICATED

Operation is authenticated, but not complete

SUCCESS

Operation has completed successfully

CANCELLED_BY_DEVICE

Operation failed because the session was cancelled by the device

CANCELLED_BY_SP

Operation failed because the session was cancelled by the service provider

CANCELLED_AUTH_METHOD_DEACTIVATED

Operation failed because the session was cancelled by the device. The device started a deactivation of authentication method(s)

CANCELLED_NEW_ACTIVATION

Operation failed because the session was cancelled when a new activation was started

EXPIRED

Operation failed because the session has expired

LOCKED

Operation failed because the device is locked

LOCKED_BY_ADMIN

Operation failed because the device is locked by admin

LOCKED_DEVICE_VERIFICATION_FAILED

Operation failed because the device is locked by device verification

LOCKED_PIN_VERIFICATION_FAILED

Operation failed because the device is locked by pin verification

LOCKED_INCORRECT_SALT_KEY_ID

Operation failed because the device is locked by incorrect salt key id

CALLBACK_FAILED

Operation failed because the session callback failed. Legacy value from synchronous callback model.

LOCKED_HW_KEY_VERIFICATION_FAILED

Operation failed because the device provided incorrect signed challenge

LOCKED_SAFETYNET_VERIFICATION_FAILED

Operation failed because the SafetyNet attestation validation failed

LOCKED_INTERMEDIATE_PUSH_VERIFICATION_FAILED

Operation failed because the intermediate push attestation validation failed

CANCELLED_INTERMEDIATE_PUSH_REQUIRED

Operation failed because of missing intermediate push attestation details

CANCELLED_SAFETYNET_REQUIRED

Operation failed because of missing SafetyNet attestation details

AUTHORIZATION_TOKEN_VERIFICATION_FAILED

Operation failed because authorization token validation failed

CANCELLED_PERFORM_RECOVERY_STARTED

Operation failed because the session was cancelled when recovery was started

FAILED_RECOVERY_DOES_NOT_EXIST

Operation failed because the recovery does not exist

LOCKED_PERFORM_RECOVERY_FAILED

Operation failed because the recovery is locked

GEOFENCING_FAILED

Operation failed because the geofencing validation failed

LOCKED_APPATTEST_VERIFICATION_FAILED

Operation failed because the App Attest validation failed

CANCELLED_APPATTEST_REQUIRED

Operation failed because of missing App Attest attestation details

LOCKED_PLAYINTEGRITY_VERIFICATION_FAILED

Operation failed because the Play Integrity validation failed

CANCELLED_PLAYINTEGRITY_REQUIRED

Operation failed because of missing Play Integrity attestation details
Session states
Session State Description

IN_PROGRESS

Session is in progress

SUCCESS

Session has completed successfully

FAILED

Operation and session failed

3.1.5. The attestation object

Field Type Description

play_integrity_status

String

Play Integrity attestation status for the device

play_integrity_date

String

Date of when the Play Integrity attestation was performed

safety_net_status

String

SafetyNet attestation status for the device

safety_net_date

String

Date of when the SafetyNet attestation was performed

app_attest_status

String

App Attest attestation status for the device. Only for iOS devices

app_attest_date

String

Date of when the App Attest attestation was performed. Only for iOS devices
App Attest statuses
App Attest status Description

VERIFIED

Attestation verification was successful

FAILED_CLIENT_APPLE_SERVER_UNAVAILABLE

Attestation failed because the Apple App Attest server was unavailable

FAILED_CLIENT_NOT_SUPPORTED

Attestation failed because App Attest is not supported on device

FAILED_CLIENT_UNEXPECTED_ERROR

Attestation failed because of an unexpected error; check the error message for details

FAILED_CLIENT_TIMEOUT

Attestation failed because the request took longer than the configured timeout

FAILED_VALIDATION_EXCEPTION

Validation of the attestation object failed because the integrity check failed
Play Integrity statuses
Google Play Integrity status Description

VERIFIED

Attestation verification was successful

FAILED_INTEGRITY_CHECK

Attestation failed because the integrity check failed

FAILED_UNRECOGNIZED_PLAY_APP

Attestation failed because the Google Play app is unrecognized

FAILED_UNLICENSED_PLAY_APP

Attestation failed because the Google Play app is unlicensed

FAILED_INCORRECT_PACKAGE_NAME

Attestation failed because of incorrect package name

FAILED_INVALID_JWS

Attestation failed because of invalid JWS format

FAILED_CLIENT_API_FAILURE

Attestation failed because Google Play Integrity returned an API exception

FAILED_CLIENT_TIMEOUT

Attestation failed due to request taking longer than the configured timeout

FAILED_INCORRECT_NONCE

Attestation failed because of incorrect nonce

FAILED_MISSING_JWS

Attestation failed because of missing JWS

FAILED_MISSING_STATUS

Attestation failed because of missing status returned from the client

FAILED_INVALID_TIMESTAMP

Attestation failed because the timestamp is not within the lifetime of the Encap server session

FAILED_CLIENT_PLAY_SERVICES_OUT_OF_DATE

Attestation failed due to client doesn’t have Google Play or the version is too old
SafetyNet statuses
SafetyNet status Description

VERIFIED

Attestation verification was successful

FAILED_INVALID_SIGNATURE

Attestation failed because the signature is invalid

FAILED_INTEGRITY_CHECK

Attestation failed because the integrity check failed

FAILED_INCORRECT_PACKAGE_NAME

Attestation failed because of incorrect package name

FAILED_INCORRECT_CERTIFICATE_DIGEST

Attestation failed because of incorrect certificate digest

FAILED_INVALID_HOSTNAME

Attestation failed because of invalid hostname

FAILED_INVALID_JWS

Attestation failed because of invalid JWS format

FAILED_CLIENT_API_FAILURE

Attestation failed because SafetyNet returned an API exception

FAILED_CLIENT_TIMEOUT

Attestation failed due to request taking longer than the configured timeout

FAILED_CLIENT_MISSING_API_KEY

Attestation failed due to missing API key

FAILED_INCORRECT_NONCE

Attestation failed because of incorrect nonce

FAILED_MISSING_JWS

Attestation failed because of missing JWS

FAILED_MISSING_STATUS

Attestation failed because of missing status returned from the client

FAILED_INVALID_TIMESTAMP

Attestation failed because the timestamp is not within the lifetime of the session

FAILED_CLIENT_PLAY_SERVICES_OUT_OF_DATE

Attestation failed due to client doesn’t have Google Play or the version is too old

3.1.6. The geofencing object

Field Type Description

country_code

String

Country code on ISO 3166-1 Alpha-2 format.

client_status

String

Status of the geofencing client operation.

server_boundary_validation

String

Status of the geofencing server validation.
Geofencing client statuses
Geofencing Client Status Description

OK

Country code obtained.

LOCATION_NOT_ENABLED

Location not requested by app or user declined.

LOCATION_TIMEOUT

Device did not obtain a location within configured accuracy before timeout.

LOCATION_MOCKED

Location was mocked/faked.

GEOCODER_NOT_SUPPORTED

Geocoder not supported on device.

GEOCODER_NETWORK_ERROR

Geocoder network or service not available.

GEOCODER_UNEXPECTED_ERROR

Unexpected geocoder error.

GEOCODER_TIMEOUT

Geocoder call did not finish within time limit.

GEOCODER_NO_RESULT_FOUND

The reverse geocode request yielded an empty result for current location.

3.1.7. The recovery object

Introduced in Encap 3.13.

Field Type Description

recovery_id

UUID

Identifier of a given recovery.

recovery_method

String

The recovery method used to set up the recovery.

recovery_status

String

The recovery status of a given recovery.

created_date

String

Date for when a given recovery was has been created.

updated_date

String

Date for when a given recovery has been updated.

recovered_date

String

Date for when a given recovery has been used.
Recovery status
Recovery status Description

ACTIVATED

Recovery has been set up for the device and is ready to be used.

DEACTIVATED

Recovery has been deactivated.

RECOVERED

Recovery has been used to recover the device.

LOCKED

Recovery has been locked.
Recovery method
Recovery method Description

CLOUD_BACKUP

Recovery is based on cloud backup and a recovery key

3.2. Constants

3.2.1. Authentication methods

Authentication method (Variant 1) Authentication method (Variant 2) Description

DEVICE

DEVICE

Device

DEVICE_PIN

DEVICE:PIN

PIN

DEVICE_IOS_FACE_ID

DEVICE:IOS_FACE_ID

FaceID for iOS

DEVICE_TOUCH_ID

DEVICE:TOUCH_ID

TouchID for iOS

DEVICE_ANDROID_FINGERPRINT

DEVICE:ANDROID_FINGERPRINT

Fingerprint for Android

DEVICE_STRONG_TOUCH_ID

DEVICE:STRONG_TOUCH_ID

TouchID for iOS where the registered fingerprints at activation time cannot be updated

DEVICE_ANDROID_BIOMETRIC_PROMPT

DEVICE:ANDROID_BIOMETRIC_PROMPT

Biometric prompt for Android

OFFLINE_DEVICE

OFFLINE

Device (offline authentication)

OFFLINE_PIN

OFFLINE:PIN

PIN (offline authentication)

OFFLINE_STRONG_TOUCH_ID

OFFLINE:STRONG_TOUCH_ID

TouchID for iOS (offline authentication)

OFFLINE_ANDROID_BIOMETRIC_PROMPT

OFFLINE:ANDROID_BIOMETRIC_PROMPT

Biometric prompt for Android (offline authentication)

OFFLINE_ANDROID_FINGERPRINT

OFFLINE:ANDROID_FINGERPRINT

Fingerprint for Android (offline authentication)

OFFLINE_IOS_FACE_ID

OFFLINE:IOS_FACE_ID

FaceID for iOS (offline authentication)

3.2.2. Authentication levels

Authentication level Description

ONE_FACTOR

Authentication level for one factor

TWO_FACTOR

Authentication level for two factors

3.2.3. Lock reason

Lock reason Description

OPEN

Device is unlocked

DEVICE_OR_PIN_VERIFICATION_FAILED

The verification of one of the authentication factors failed. Wrong device and/or a second-factor error (incorrect PIN code or biometrics)

LOCKED_BY_ADMIN

The device is locked by an administrative operation

DEVICE_VERIFICATION_FAILED

The verification of the device factor failed for an authentication

PIN_VERIFICATION_FAILED

The verification of the second authentication factor failed (incorrect PIN code or biometrics)

INCORRECT_SALT_KEY_ID

The device provided an incorrect Salt-key ID during authentication

HW_KEY_VERIFICATION_FAILED

The verification of the hardware-protected key failed (the key provided was incorrect)

OTP_VERIFICATION_FAILED

The device is locked due to a failed offline authentication, caused by OTP verification code mismatch

SAFETYNET_VERIFICATION_FAILED

The verification of the SafetyNet attestation failed

INTERMEDIATE_PUSH_VERIFICATION_FAILED

The verification of the intermediate push attestation failed

APPATTEST_VERIFICATION_FAILED

The verification of the App Attest attestation failed

PLAYINTEGRITY_VERIFICATION_FAILED

The verification of the Play Integrity attestation failed

3.2.4. Session purpose

Purpose Description

ACTIVATION

Activation/enrollment of new device.

AUTHENTICATION

Authentication.

AUTH_AND_ACTIVATE

Activating an additional auth method for an existing device.

AUTH_AND_DEACTIVATE

Deactivating an auth method for an existing device.

ADD_OR_UPDATE_RECOVERY

Setting up recovery for an existing device.

PERFORM_RECOVERY

An existing recovery has been used to perform a recovery to a new device.

DELETE_RECOVERY

An existing recovery has been deleted.

PERFORM_RECOVERY_NOTIFICATION

A notification sent to the old device when performing a recovery.

3.3. Enrollment

Enrollments are used to create a binding between a supported customer mobile device/application instance and the Encap server, which can then be used for subsequent secure mobile authentication operations.

When enrollment is started, the Encap server returns a unique activation code which must be conveyed to the customer and supplied to the mobile application instance along with any additional biometric or non-biometric authentication factors. The underlying Encap mobile authentication technology will then complete a complex cryptographic handshake between the application instance and the Encap server which results in a secure binding between the application instance and the service, completing the enrollment process.

It is the responsibility of the client to establish a suitably secure trust channel in order to convey the activation code to the customer. For example, this can be done by displaying the code QR format in a previously-authenticated web session, where it can be captured by the device camera, but ultimately any secure, trusted channel can be used.

The enrollment process is asynchronous – a start operation is used to commence enrollment which then proceeds in the background. Successful completion or failure of an ongoing enrollment process can then be detected either by polling additional API operations or via a client-supplied REST callback interface. These two styles are illustrated below:

enrollWithCallback
enrollNoCallback

3.3.1. The enrollment object

Field Type Description

id

UUID

The UUID for the enrollment session

activation_code

String

The code to use for activation

application_id

String

The application ID for the device

callback_address

String

The callback address for the device

device_id

UUID

The UUID for the device

session_created_time

String

The time for when the session was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

session_expiry_time

String

The time for when the session will expire. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

authentication_level

String

The authentication level of the enrollment. See authentication levels for options

activated_authentication_methods

Array

List of activated authentication methods (Variant 2). See authentication methods for possible values

push_address

String

The push address for the device, this address is used when sending push to the device using FCM or APNS.

custom_push_payload

String

A custom payload send to the device in the push notification.

recovery_lock

Boolean

Explicit setting for the device to lock/unlock recovery. Introduced in Encap 3.13

post_operation_context

Object

Operation context object that contains details to be shown after a successful the authentication. See operation_context object for details.

attestation

Object

Attestation object that contains details for all the attestations performed for the device. See attestation object for details.

risk_attributes

Array

List that contains name and value for all risk attributes. See risk_attributes object for details.

session_status

Object

Status object that contains status details of the session. See session_status object for details.

location

Object

Location object that contains location details, see location object for details.

geofencing

Object

Geofencing object that contains details of device location and geofencing validation. See geofencing object for details. Introduced in Encap 3.14

3.3.2. Start enrollment of device

POST /api/smart-device/v1/enrollments

To start an enrollment of a device you create an enrollment object

Arguments
Path Type Required Description

application_id

String

Yes

The application id for the configuration to use during the enrollment

authentication_level

String

No

The authentication level for the operation. See authentication levels for options. If not provided default level TWO_FACTOR will be used

callback_address

String

No

The callback address for the device

session_expiry_time

Number

No

Life time in ms for for the session before it expires

custom_push_payload

String

No

A custom payload send to the device in the push notification, the payload can maximum contain 256 bytes and all characters must be in the Basic Multilingual Plane. Please note that the payload is sent in plain text and that the push channel is not a secure channel, to send data to the device over a secure channel use the post/pre operation context.

recovery_lock

Boolean

No

Allows to override recovery setting from app config and disable recovery during REST enrollment. Introduced in Encap 3.13.

post_operation_context

Object

No

Operation context object that contains details to be shown after a successful the authentication. See operation_context object for details.
Example request body
{
  "application_id" : "encap",
  "session_expiry_time" : 3000,
  "callback_address" : "http://callback.url.com",
  "post_operation_context" : {
    "context_title_b64" : "VG1salpWUnBkR3hs",
    "context_content_b64" : "VG1salpWUnBkR3hs",
    "context_mime" : "text/plain"
  },
  "authentication_level" : "ONE_FACTOR",
  "custom_push_payload" : "ServerA",
  "recovery_lock" : false
}
Returns

Returns an enrollment object if the enrollment process is successfully initiated. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/enrollments' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "application_id" : "encap",
  "session_expiry_time" : 3000,
  "callback_address" : "http://callback.url.com",
  "post_operation_context" : {
    "context_title_b64" : "VG1salpWUnBkR3hs",
    "context_content_b64" : "VG1salpWUnBkR3hs",
    "context_mime" : "text/plain"
  },
  "authentication_level" : "ONE_FACTOR",
  "custom_push_payload" : "ServerA",
  "recovery_lock" : false
}'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 36bc2fc7-373d-4a22-9cdd-7175f1d4daa9
Content-Type: application/json
Content-Length: 1899

{
  "id" : "f97136dc-4298-42ab-8521-55009df8db4a",
  "application_id" : "encap",
  "activation_code" : "123456",
  "callback_address" : "callback",
  "device_id" : "4b9cdbdc-e5b9-49fe-850a-048c190cb459",
  "session_created_time" : "2023-09-28T11:29:39.448UTC",
  "session_expiry_time" : "2023-09-28T13:29:39.448UTC",
  "authentication_level" : "TWO_FACTOR",
  "activated_authentication_methods" : [ "DEVICE", "DEVICE:PIN", "DEVICE:TOUCH_ID" ],
  "location" : {
    "accuracy" : "0.564",
    "altitude" : "76.2352.3563",
    "latitude" : "12.34234.143",
    "longitude" : "32.24314.1431"
  },
  "post_operation_context" : {
    "context_title_b64" : "VkdsMGJHVT0=",
    "context_content_b64" : "UTI5dWRHVnVkQT09",
    "context_mime" : "MIME"
  },
  "risk_attributes" : [ {
    "name" : "is_debuggable",
    "value" : "true"
  }, {
    "name" : "is_unknown_sources_enabled",
    "value" : "true"
  }, {
    "name" : "is_debugger_connected",
    "value" : "true"
  }, {
    "name" : "input_method",
    "value" : "input"
  }, {
    "name" : "is_emulator",
    "value" : "true"
  }, {
    "name" : "operating_system_version",
    "value" : "2.3"
  }, {
    "name" : "client_side_ip",
    "value" : "[\"192.168.0.1\"]"
  } ],
  "session_status" : {
    "status" : "IN_PROGRESS",
    "description" : "Operation is in progress",
    "state" : "IN_PROGRESS"
  },
  "attestation" : {
    "safety_net_status" : "VERIFIED",
    "safety_net_date" : "2023-09-28T11:29:39.448UTC",
    "app_attest_status" : "VERIFIED",
    "app_attest_date" : "2023-09-28T11:29:39.448UTC",
    "play_integrity_status" : "VERIFIED",
    "play_integrity_date" : "2023-09-28T11:29:39.448UTC"
  },
  "geofencing" : {
    "country_code" : "NO",
    "client_status" : "OK",
    "server_boundary_validation" : "SUCCESS"
  },
  "push_address" : "123409238402394f3413r2e2f",
  "custom_push_payload" : "ServerA",
  "recovery_lock" : false
}

3.3.3. Get enrollment details

GET /api/smart-device/v1/enrollments/{id}

Getting the enrollment details lets you know the state of the enrollment and if finished it gives you access to risk data and all other attributes created as part of the enrollment process.

Returns

Returns an enrollment object if a valid identifier was provided, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/enrollments/f97136dc-4298-42ab-8521-55009df8db4a' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 3ef2c351-de51-4393-bafb-27938c2c18c5
Content-Type: application/json
Content-Length: 1899

{
  "id" : "f97136dc-4298-42ab-8521-55009df8db4a",
  "application_id" : "encap",
  "activation_code" : "123456",
  "callback_address" : "callback",
  "device_id" : "7b57884f-2750-42fa-8282-b00967d68368",
  "session_created_time" : "2023-09-28T11:29:39.276UTC",
  "session_expiry_time" : "2023-09-28T13:29:39.276UTC",
  "authentication_level" : "TWO_FACTOR",
  "activated_authentication_methods" : [ "DEVICE", "DEVICE:PIN", "DEVICE:TOUCH_ID" ],
  "location" : {
    "accuracy" : "0.564",
    "altitude" : "76.2352.3563",
    "latitude" : "12.34234.143",
    "longitude" : "32.24314.1431"
  },
  "post_operation_context" : {
    "context_title_b64" : "VkdsMGJHVT0=",
    "context_content_b64" : "UTI5dWRHVnVkQT09",
    "context_mime" : "MIME"
  },
  "risk_attributes" : [ {
    "name" : "is_debuggable",
    "value" : "true"
  }, {
    "name" : "is_unknown_sources_enabled",
    "value" : "true"
  }, {
    "name" : "is_debugger_connected",
    "value" : "true"
  }, {
    "name" : "input_method",
    "value" : "input"
  }, {
    "name" : "is_emulator",
    "value" : "true"
  }, {
    "name" : "operating_system_version",
    "value" : "2.3"
  }, {
    "name" : "client_side_ip",
    "value" : "[\"192.168.0.1\"]"
  } ],
  "session_status" : {
    "status" : "IN_PROGRESS",
    "description" : "Operation is in progress",
    "state" : "IN_PROGRESS"
  },
  "attestation" : {
    "safety_net_status" : "VERIFIED",
    "safety_net_date" : "2023-09-28T11:29:39.276UTC",
    "app_attest_status" : "VERIFIED",
    "app_attest_date" : "2023-09-28T11:29:39.276UTC",
    "play_integrity_status" : "VERIFIED",
    "play_integrity_date" : "2023-09-28T11:29:39.276UTC"
  },
  "geofencing" : {
    "country_code" : "NO",
    "client_status" : "OK",
    "server_boundary_validation" : "SUCCESS"
  },
  "push_address" : "123409238402394f3413r2e2f",
  "custom_push_payload" : "ServerA",
  "recovery_lock" : false
}

3.3.4. Cancel enrollment

DELETE /api/smart-device/v1/enrollments/{sessionId}

To cancel an enrollment in progress thereby preventing the device from finishing the enrollment process

Returns

Returns 204 No Content if a valid identifier was provided and the process was canceled. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/enrollments/f97136dc-4298-42ab-8521-55009df8db4a' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: 24fe4fbd-1e0b-46d0-8e69-6ce4b5d4e882

3.3.5. Callback

If ´callback_address´ is set, this will be a POST to the Service Provider’s ´callback_address´ with an enrollment object identical to the object that the Service Provider would get if get enrollment details was called.

See callback implementation and callback usage for more details.

Example request
POST /api/callback/v1/enroll HTTP/1.1
Content-Type: application/json
Content-Length: 1392
Host: localhost:8080

{
  "id" : "eb662bc8-cb42-4b8b-a8ee-d54a083f2157",
  "application_id" : "encap",
  "activation_code" : "123456",
  "callback_address" : "http://callback.url.com",
  "device_id" : "36b98586-76ae-4321-9e27-9d845163cd5f",
  "session_created_time" : "2023-09-28T11:29:38.530UTC",
  "session_expiry_time" : "2023-09-28T11:29:38.530UTC",
  "authentication_level" : "TWO_FACTOR",
  "activated_authentication_methods" : [ "DEVICE", "DEVICE:PIN" ],
  "location" : {
    "accuracy" : "0.564",
    "altitude" : "76.2352.3563",
    "latitude" : "12.34234.143",
    "longitude" : "32.24314.1431"
  },
  "post_operation_context" : {
    "context_title_b64" : "VG1salpWUnBkR3hs",
    "context_content_b64" : "VG1salpWUnBkR3hs",
    "context_mime" : "text/plain"
  },
  "risk_attributes" : [ {
    "name" : "is_debuggable",
    "value" : "true"
  }, {
    "name" : "is_unknown_sources_enabled",
    "value" : "true"
  }, {
    "name" : "is_debugger_connected",
    "value" : "true"
  }, {
    "name" : "input_method",
    "value" : "input"
  }, {
    "name" : "is_emulator",
    "value" : "true"
  }, {
    "name" : "operating_system_version",
    "value" : "2.3"
  }, {
    "name" : "client_side_ip",
    "value" : "[\"192.168.0.1\"]"
  } ],
  "session_status" : {
    "status" : "SUCCESS",
    "description" : "Operation has completed successfully",
    "state" : "SUCCESS"
  },
  "recovery_lock" : false
}
Example response
HTTP/1.1 200 OK

3.3.6. Re-enrollment

Re-enrollment enables users to be re-enrolled and create new credentials on the same device id given that they are still using the same device as they were originally enrolled on. This will remove complexity from Service Providers allowing them to reuse the device id instead of creating a new one.

re enroll
Limitations

  • Reactivation does not work on registrations that has been deactivated either by the Service Provider or by the end-user. In these scenarios the user needs to start a new enrollment.

  • End-user must be on the same device. Encap validates the device hash during the re-enrollment to confirm that the end-user is still using the same device. Generally, the device hash will remain unchanged after a re-installation of the app, but we have identified the following exceptions:

    • Android:

      • Factory reset may change the device hash.

      • Reinstalling the app after an upgrade from Android version 7 or below to 8 or above will cause changes to the device hash.

      • The device hash will not be carried over to a new device.

    • iOS:

      • Reinstalling the app from a non-encrypted backup after a factory reset

      • The device hash will not be carried over to a new device.

Start re-enrollment of device
POST /api/smart-device/v1/enrollments

To start a re-enrollment of a device you create an enrollment object that contains device_id parameter. application_id is optional in this case.

Arguments
Path Type Required Description

device_id

UUID

Yes

The device id for the configuration to use during the re-enrollment

application_id

String

No

The application id for the configuration to use during the enrollment. If not provided we will use application id of the old registration.It is not allowed to change application id in e re-enrollment, if application id is provided it has to match the application id of the old registration.

authentication_level

String

No

The authentication level for the operation. See authentication levels for options. If not provided default level TWO_FACTOR will be used

callback_address

String

No

The callback address for the device

session_expiry_time

Number

No

Life time in ms for for the session before it expires

custom_push_payload

String

No

A custom payload send to the device in the push notification, the payload can maximum contain 256 bytes and all characters must be in the Basic Multilingual Plane. Please note that the payload is sent in plain text and that the push channel is not a secure channel, to send data to the device over a secure channel use the post/pre operation context.

post_operation_context

Object

No

Operation context object that contains details to be shown after a successful the authentication. See operation_context object for details.
Example request body
{
  "application_id" : "encap",
  "session_expiry_time" : 3000,
  "callback_address" : "http://callback.url.com",
  "post_operation_context" : {
    "context_title_b64" : "VG1salpWUnBkR3hs",
    "context_content_b64" : "VG1salpWUnBkR3hs",
    "context_mime" : "text/plain"
  },
  "authentication_level" : "ONE_FACTOR",
  "custom_push_payload" : "ServerA",
  "device_id" : "74721950-0db7-43ed-a230-fd6690efbc58"
}
Returns

Returns an enrollment object if the enrollment process is successfully initiated. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/enrollments' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "application_id" : "encap",
  "session_expiry_time" : 3000,
  "callback_address" : "http://callback.url.com",
  "post_operation_context" : {
    "context_title_b64" : "VG1salpWUnBkR3hs",
    "context_content_b64" : "VG1salpWUnBkR3hs",
    "context_mime" : "text/plain"
  },
  "authentication_level" : "ONE_FACTOR",
  "custom_push_payload" : "ServerA",
  "device_id" : "74721950-0db7-43ed-a230-fd6690efbc58"
}'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 5b17fa6f-d7b0-40ff-a9bc-9f854eb8aadc
Content-Type: application/json
Content-Length: 1899

{
  "id" : "f97136dc-4298-42ab-8521-55009df8db4a",
  "application_id" : "encap",
  "activation_code" : "123456",
  "callback_address" : "callback",
  "device_id" : "61155300-8ecb-4c9b-bef0-18e9e81b1b1c",
  "session_created_time" : "2023-09-28T11:29:38.656UTC",
  "session_expiry_time" : "2023-09-28T13:29:38.656UTC",
  "authentication_level" : "TWO_FACTOR",
  "activated_authentication_methods" : [ "DEVICE", "DEVICE:PIN", "DEVICE:TOUCH_ID" ],
  "location" : {
    "accuracy" : "0.564",
    "altitude" : "76.2352.3563",
    "latitude" : "12.34234.143",
    "longitude" : "32.24314.1431"
  },
  "post_operation_context" : {
    "context_title_b64" : "VkdsMGJHVT0=",
    "context_content_b64" : "UTI5dWRHVnVkQT09",
    "context_mime" : "MIME"
  },
  "risk_attributes" : [ {
    "name" : "is_debuggable",
    "value" : "true"
  }, {
    "name" : "is_unknown_sources_enabled",
    "value" : "true"
  }, {
    "name" : "is_debugger_connected",
    "value" : "true"
  }, {
    "name" : "input_method",
    "value" : "input"
  }, {
    "name" : "is_emulator",
    "value" : "true"
  }, {
    "name" : "operating_system_version",
    "value" : "2.3"
  }, {
    "name" : "client_side_ip",
    "value" : "[\"192.168.0.1\"]"
  } ],
  "session_status" : {
    "status" : "IN_PROGRESS",
    "description" : "Operation is in progress",
    "state" : "IN_PROGRESS"
  },
  "attestation" : {
    "safety_net_status" : "VERIFIED",
    "safety_net_date" : "2023-09-28T11:29:38.656UTC",
    "app_attest_status" : "VERIFIED",
    "app_attest_date" : "2023-09-28T11:29:38.656UTC",
    "play_integrity_status" : "VERIFIED",
    "play_integrity_date" : "2023-09-28T11:29:38.656UTC"
  },
  "geofencing" : {
    "country_code" : "NO",
    "client_status" : "OK",
    "server_boundary_validation" : "SUCCESS"
  },
  "push_address" : "123409238402394f3413r2e2f",
  "custom_push_payload" : "ServerA",
  "recovery_lock" : false
}

3.4. Authentication

Authentication operations are used to authenticate customers via previously-enrolled device/application instances. The authentication process is fully contextual, with context information supplied via the API that can be displayed to the customer before and/or after authentication has completed.

The authentication process is asynchronous – a start operation is used to commence an authentication process which then proceeds in the background. Successful completion or failure of an ongoing authentication process can then be detected either by polling via additional API requests or via a client-implemented REST callback interface. These two styles are illustrated below:

authWithCallback
authNoCallback

3.4.1. The authentication object

Field Type Description

id

UUID

The UUID for the authentication session

authentication_level

String

The authentication level of the enrollment. See authentication levels for options

authentication_method

String

The authentication method for the operation (Variant 1). See authentication methods for possible values

callback_address

String

The callback address for the device

device_id

UUID

The UUID for the device

push_sent

Boolean

Boolean for if a push has been sent or not

session_created_time

String

The time for when the session was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

session_expiry_time

String

The time for when the session will expire. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

purpose

String

The purpose of the session. See session purpose for details.

client_data

String

The base64 encoded client data used by the client in identify.

custom_push_payload

String

A custom payload send to the device in the push notification.

pre_operation_context

Object

Operation context object that contains details to be shown before the authentication.See operation_context object for details.

post_operation_context

Object

Operation context object that contains details to be shown after a successful the authentication. See operation_context object for details.

risk_attributes

Array

List that contains name and value for all risk attributes. See risk_attributes object for details.

location

Object

Location object that contains location details, see location object for details.

session_status

Object

Status object that contains status details of the session. See session_status object for details.

attestation

Object

Attestation object that contains details for all the attestations performed for the device. See attestation object for details.

geofencing

Object

Geofencing object that contains details of device location and geofencing validation. See geofencing object for details. Introduced in Encap 3.14

3.4.2. Start authentication

POST /api/smart-device/v1/authentications

To start an authentication you create an authentication object

Arguments
Path Type Required Description

device_id

UUID

Yes

The UUID for the device

authentication_level

String

No

The authentication level for the operation. See authentication levels for options. If not provided default level TWO_FACTOR will be used

authentication_method

String

No

The authentication method for the operation (Variant 1). See authentication methods for possible values

callback_address

String

No

The callback address for the device

session_expiry_time

Number

No

Life time in ms for for the session before it expires

custom_push_payload

String

No

A custom payload send to the device in the push notification, the payload can maximum contain 256 bytes and all characters must be in the Basic Multilingual Plane. Please note that the payload is sent in plain text and that the push channel is not a secure channel, to send data to the device over a secure channel use the post/pre operation context.

send_push

Boolean

No

Choose to send push or not. It requires that push notifications are allowed for the given appId. Default is true. Introduced in Encap 3.12.

pre_operation_context

Object

No

Operation context object that contains details to be shown before the authentication.See operation_context object for details.

post_operation_context

Object

No

Operation context object that contains details to be shown after a successful the authentication. See operation_context object for details.
Example request body
{
  "device_id" : "19a0bf3d-557c-4654-9ff8-46e49be07af4",
  "authentication_level" : "TWO_FACTOR",
  "authentication_method" : "DEVICE_PIN",
  "callback_address" : "http://callback.url.com",
  "session_expiry_time" : 30000,
  "pre_operation_context" : {
    "context_title_b64" : "VUhKbFZHbDBiR1U9",
    "context_content_b64" : "VUhKbFEyOXVkR1Z1ZEE9PQ==",
    "context_mime" : "text/plain"
  },
  "post_operation_context" : {
    "context_title_b64" : "VUc5emRGUnBkR3hs",
    "context_content_b64" : "VUc5emRFTnZiblJsYm5RPQ==",
    "context_mime" : "text/plain"
  },
  "send_push" : true,
  "custom_push_payload" : "ServerA"
}
Returns

Returns an authentication object if authentication process is successfully initiated. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/authentications' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "device_id" : "19a0bf3d-557c-4654-9ff8-46e49be07af4",
  "authentication_level" : "TWO_FACTOR",
  "authentication_method" : "DEVICE_PIN",
  "callback_address" : "http://callback.url.com",
  "session_expiry_time" : 30000,
  "pre_operation_context" : {
    "context_title_b64" : "VUhKbFZHbDBiR1U9",
    "context_content_b64" : "VUhKbFEyOXVkR1Z1ZEE9PQ==",
    "context_mime" : "text/plain"
  },
  "post_operation_context" : {
    "context_title_b64" : "VUc5emRGUnBkR3hs",
    "context_content_b64" : "VUc5emRFTnZiblJsYm5RPQ==",
    "context_mime" : "text/plain"
  },
  "send_push" : true,
  "custom_push_payload" : "ServerA"
}'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 41c41ce5-ee36-4dc9-84b8-3c2cdc93e19b
Content-Type: application/json
Content-Length: 1987

{
  "id" : "9e07806d-2350-4b11-96a4-86b01cbf2afd",
  "authentication_level" : "TWO_FACTOR",
  "authentication_method" : "DEVICE_PIN",
  "callback_address" : "callback",
  "device_id" : "c237c18e-8ccf-4dc8-bd28-e9510b245c0c",
  "push_sent" : true,
  "custom_push_payload" : "ServerA",
  "session_created_time" : "2023-09-28T11:29:35.627UTC",
  "session_expiry_time" : "2023-09-28T13:29:35.627UTC",
  "pre_operation_context" : {
    "context_title_b64" : "VUhKbFZHbDBiR1U9",
    "context_content_b64" : "VUhKbFEyOXVkR1Z1ZEE9PQ==",
    "context_mime" : "MIME"
  },
  "post_operation_context" : {
    "context_title_b64" : "VUc5emRGUnBkR3hs",
    "context_content_b64" : "VUc5emRFTnZiblJsYm5RPQ==",
    "context_mime" : "MIME"
  },
  "location" : {
    "accuracy" : "0.564",
    "altitude" : "76.2352.3563",
    "latitude" : "12.34234.143",
    "longitude" : "32.24314.1431"
  },
  "session_status" : {
    "status" : "IN_PROGRESS",
    "description" : "Operation is in progress",
    "state" : "IN_PROGRESS"
  },
  "risk_attributes" : [ {
    "name" : "is_debuggable",
    "value" : "true"
  }, {
    "name" : "is_unknown_sources_enabled",
    "value" : "true"
  }, {
    "name" : "is_debugger_connected",
    "value" : "true"
  }, {
    "name" : "input_method",
    "value" : "input"
  }, {
    "name" : "is_emulator",
    "value" : "true"
  }, {
    "name" : "operating_system_version",
    "value" : "2.3"
  }, {
    "name" : "client_side_ip",
    "value" : "[\"192.168.0.1\"]"
  } ],
  "client_data" : "YWJjZGVmMTIzNDU2",
  "attestation" : {
    "safety_net_status" : "VERIFIED",
    "safety_net_date" : "2023-09-28T11:29:35.626UTC",
    "app_attest_status" : "VERIFIED",
    "app_attest_date" : "2023-09-28T11:29:35.626UTC",
    "play_integrity_status" : "VERIFIED",
    "play_integrity_date" : "2023-09-28T11:29:35.626UTC"
  },
  "geofencing" : {
    "country_code" : "NO",
    "client_status" : "OK",
    "server_boundary_validation" : "SUCCESS"
  },
  "purpose" : "AUTHENTICATION"
}

3.4.3. Get authentication details

GET /api/smart-device/v1/authentications/{id}

Getting the authentication details lets you know the state of the authentication and if finished it gives you access to risk data and all other attributes created as part of the authentication process.

Returns

Returns an authentication object if a valid identifier was provided, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/authentications/9e07806d-2350-4b11-96a4-86b01cbf2afd' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 3c564ce2-0c45-4acc-8929-5f3037124dd5
Content-Type: application/json
Content-Length: 1987

{
  "id" : "9e07806d-2350-4b11-96a4-86b01cbf2afd",
  "authentication_level" : "TWO_FACTOR",
  "authentication_method" : "DEVICE_PIN",
  "callback_address" : "callback",
  "device_id" : "699e60a4-f4f1-46a8-a47c-e138d947f5af",
  "push_sent" : true,
  "custom_push_payload" : "ServerA",
  "session_created_time" : "2023-09-28T11:29:35.429UTC",
  "session_expiry_time" : "2023-09-28T13:29:35.429UTC",
  "pre_operation_context" : {
    "context_title_b64" : "VUhKbFZHbDBiR1U9",
    "context_content_b64" : "VUhKbFEyOXVkR1Z1ZEE9PQ==",
    "context_mime" : "MIME"
  },
  "post_operation_context" : {
    "context_title_b64" : "VUc5emRGUnBkR3hs",
    "context_content_b64" : "VUc5emRFTnZiblJsYm5RPQ==",
    "context_mime" : "MIME"
  },
  "location" : {
    "accuracy" : "0.564",
    "altitude" : "76.2352.3563",
    "latitude" : "12.34234.143",
    "longitude" : "32.24314.1431"
  },
  "session_status" : {
    "status" : "IN_PROGRESS",
    "description" : "Operation is in progress",
    "state" : "IN_PROGRESS"
  },
  "risk_attributes" : [ {
    "name" : "is_debuggable",
    "value" : "true"
  }, {
    "name" : "is_unknown_sources_enabled",
    "value" : "true"
  }, {
    "name" : "is_debugger_connected",
    "value" : "true"
  }, {
    "name" : "input_method",
    "value" : "input"
  }, {
    "name" : "is_emulator",
    "value" : "true"
  }, {
    "name" : "operating_system_version",
    "value" : "2.3"
  }, {
    "name" : "client_side_ip",
    "value" : "[\"192.168.0.1\"]"
  } ],
  "client_data" : "YWJjZGVmMTIzNDU2",
  "attestation" : {
    "safety_net_status" : "VERIFIED",
    "safety_net_date" : "2023-09-28T11:29:35.428UTC",
    "app_attest_status" : "VERIFIED",
    "app_attest_date" : "2023-09-28T11:29:35.428UTC",
    "play_integrity_status" : "VERIFIED",
    "play_integrity_date" : "2023-09-28T11:29:35.428UTC"
  },
  "geofencing" : {
    "country_code" : "NO",
    "client_status" : "OK",
    "server_boundary_validation" : "SUCCESS"
  },
  "purpose" : "AUTHENTICATION"
}

3.4.4. Cancel authentication

DELETE /api/smart-device/v1/authentications/{sessionId}

To cancel an authentication in progress thereby preventing the device from finishing the authentication process

Returns

Returns 204 No Content if a valid identifier was provided and the process was canceled. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/authentications/9e07806d-2350-4b11-96a4-86b01cbf2afd' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: 1c18de25-d09d-41b1-86e8-84484ea35bf4

3.4.5. Callback

If ´callback_address´ is set, this will be a POST to the Service Provider’s ´callback_address´ with an authentication object identical to the object that the Service Provider would get if get authentication details was called.

See callback implementation and callback usage for more details.

Example request
POST /api/callback/v1/auth HTTP/1.1
Content-Type: application/json
Content-Length: 1480
Host: localhost:8080

{
  "id" : "0a0a5795-7172-4141-9fa9-1ad2086ea86a",
  "authentication_level" : "TWO_FACTOR",
  "authentication_method" : "DEVICE_PIN",
  "callback_address" : "http://callback.url.com",
  "device_id" : "64b94533-03a7-4a52-8591-266243ccb32c",
  "push_sent" : false,
  "session_created_time" : "2023-09-28T11:29:34.665UTC",
  "session_expiry_time" : "2023-09-28T11:29:34.665UTC",
  "pre_operation_context" : {
    "context_title_b64" : "VUhKbFZHbDBiR1U9",
    "context_content_b64" : "VUhKbFEyOXVkR1Z1ZEE9PQ==",
    "context_mime" : "text/plain"
  },
  "post_operation_context" : {
    "context_title_b64" : "VUc5emRGUnBkR3hs",
    "context_content_b64" : "VUc5emRFTnZiblJsYm5RPQ==",
    "context_mime" : "text/plain"
  },
  "location" : {
    "accuracy" : "0.564",
    "altitude" : "76.2352.3563",
    "latitude" : "12.34234.143",
    "longitude" : "32.24314.1431"
  },
  "session_status" : {
    "status" : "SUCCESS",
    "description" : "Operation has completed successfully",
    "state" : "SUCCESS"
  },
  "risk_attributes" : [ {
    "name" : "is_debuggable",
    "value" : "true"
  }, {
    "name" : "is_unknown_sources_enabled",
    "value" : "true"
  }, {
    "name" : "is_debugger_connected",
    "value" : "true"
  }, {
    "name" : "input_method",
    "value" : "input"
  }, {
    "name" : "is_emulator",
    "value" : "true"
  }, {
    "name" : "operating_system_version",
    "value" : "2.3"
  }, {
    "name" : "client_side_ip",
    "value" : "[\"192.168.0.1\"]"
  } ]
}
Example response
HTTP/1.1 200 OK

3.5. Offline Authentication

An API for doing offline authentications. Offline meaning the device does not have access to the internet. Data is transferred as a verification string to the device (for instance through a QR-code), and verified by a one time password

The offline flow runs as follows:

offlineAuth

3.5.1. The offline authentication object

Field Type Description

id

UUID

The UUID of the authentication session

context

String

The context used in the authentication

verification_data

String

String of data transferable to the client to complete the authentication

device_id

UUID

The UUID for the device

session_created_time

String

The time for when the session was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

session_expiry_time

String

The time for when the session will expire. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

authentication_method

String

The authentication method for the operation (Variant 1). See authentication methods for possible values

authentication_level

String

The authentication level of the enrollment. See authentication levels for options

session_status

Object

Status object that contains status details of the session. See session_status object for details.

3.5.2. Begin offline authentication

POST /api/smart-device/v1/offline-authentications

To start an offline authentication, you create an offline authentication object

Arguments
Path Type Required Description

device_id

UUID

Yes

The UUID of the device you want to authenticate

session_expiry_time

Number

No

Amount of time until the authentication will expire in milliseconds

authentication_method

String

No

Authentication method you want to use (Variant 1). See authentication methods for possible values

context

String

No

The context used in the authentication. This must be a UTF-8 String no larger than 300 bytes (length may vary dependent on amount of special characters)
Example request body
{
  "device_id" : "bbf64c25-9ff1-48a1-95b7-61772336c439",
  "context" : "Transaction amount: €2000.-",
  "authentication_method" : "OFFLINE_PIN",
  "session_expiry_time" : 300000
}
Returns

Returns an offline authentication object if authentication process is successfully initiated. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/offline-authentications' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "device_id" : "bbf64c25-9ff1-48a1-95b7-61772336c439",
  "context" : "Transaction amount: €2000.-",
  "authentication_method" : "OFFLINE_PIN",
  "session_expiry_time" : 300000
}'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 217e39b0-dc9b-46a2-a725-5a494a679dc9
Content-Type: application/json
Content-Length: 591

{
  "id" : "363ec0de-0429-490b-97e5-5acef11fafb5",
  "session_created_time" : "2023-09-28T11:29:40.461UTC",
  "session_expiry_time" : "2023-09-28T11:34:40.461UTC",
  "session_status" : {
    "status" : "IN_PROGRESS",
    "description" : "Operation is in progress",
    "state" : "IN_PROGRESS"
  },
  "device_id" : "652b888e-6f60-42a5-bedb-6f82cde42936",
  "authentication_method" : "OFFLINE_PIN",
  "authentication_level" : "TWO_FACTOR",
  "context" : "Transaction amount: €2000.-",
  "verification_data" : "1,t+J5to7Mq1r3MkSLSeHxpg,12,VHJhbnNhY3Rpb24gYW1vdW50OiDigqwyMDAwLi0,6,b1ff91bf"
}

3.5.3. Verify offline authentication

POST /api/smart-device/v1/offline-authentications/{id}/verifications

To verify an offline authentication session, you send in a one-time-password

Arguments
Path Type Required Description

otp

String

YES

Client generated OTP to verify
Example request body
{
  "otp" : "123456"
}
Returns

Returns the verification status, and the number of remaining attempts if the call is successful. The status can be offline verification status. Returns an error object if something goes wrong.

Response fields
Field Type Description

status

String

The result of the authentication. See offline verification status for possible values.

remaining_attempts

Number

Number of attempts before the authentication method gets locked
Verification status values
Status Description

SUCCESS

Operation has completed successfully

FAILURE

Operation failed because the session was cancelled by the device

EXPIRED

Operation failed because the session has expired

LOCKED_DEVICE

Operation failed because the device is locked

LOCKED_AUTH_METHOD

Operation failed because the authentication method is locked
Example request
$ curl 'http://localhost:8080/api/smart-device/v1/offline-authentications/dcd1d0dd-0baa-4367-a0b1-73e79b64148e/verifications' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "otp" : "123456"
}'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 5a0eea7a-ad3a-4f4e-8530-32231305528c
Content-Type: application/json
Content-Length: 54

{
  "status" : "FAILURE",
  "remaining_attempts" : 2
}

3.5.4. Get authentication details

GET /api/smart-device/v1/offline-authentications/{id}

Getting the authentication session details lets you know the state of the authentication and all other attributes created as part of the offline-authentication process.

Returns

Returns an offline authentication object if a valid identifier was provided, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/offline-authentications/70dab7d8-2994-4c29-b9e2-37b7901b1775' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 365074ae-48e1-4bae-ae1f-8dc0eb6c428a
Content-Type: application/json
Content-Length: 591

{
  "id" : "9ff46737-4903-4deb-aee0-a2e16291c31f",
  "session_created_time" : "2023-09-28T11:29:40.389UTC",
  "session_expiry_time" : "2023-09-28T11:34:40.389UTC",
  "session_status" : {
    "status" : "IN_PROGRESS",
    "description" : "Operation is in progress",
    "state" : "IN_PROGRESS"
  },
  "device_id" : "652b888e-6f60-42a5-bedb-6f82cde42936",
  "authentication_method" : "OFFLINE_PIN",
  "authentication_level" : "TWO_FACTOR",
  "context" : "Transaction amount: €2000.-",
  "verification_data" : "1,/H4/v0Gulv1qYLoSzRGCXw,12,VHJhbnNhY3Rpb24gYW1vdW50OiDigqwyMDAwLi0,6,c66f3998"
}

3.5.5. Cancel authentication

DELETE /api/smart-device/v1/offline-authentications/{id}

To cancel an authentication session in progress thereby preventing the device from finishing the authentication process

Returns

Returns an empty response if the operation succeeds. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/offline-authentications/ef4a9ba1-a0c9-4faa-a945-339168d079ec' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: ab6a651e-82d4-4d39-96b3-09adb1861d74

3.6. Device

Each successful enrollment process registers a new device, this API can retrieve details for a device and deactivate it.

3.6.1. The device object

Field Type Description

id

UUID

The UUID for the device

application_id

String

The application ID for the device

current_client_api_version

String

The client API version used in the device’s last operation

activated_client_api_version

String

The client API version that the device was originally activated on

activated_encap_release

String

Encap server release version that the device was originally activated on

device_hash

String

SHA256 hash of the unique hardware device ID of the client device.

salt_hash

String

SHA256 hash of the device client salt.

operating_system_type

String

The operating system type of the device

activated_authentication_methods

Array

List of activated authentication methods (Variant 2). See authentication methods for possible values

activation_time

String

The time for when the device was originally activated

last_used_time

String

The time for when the device last made an operation

lock

Object

An lock object containing lock details. Only present when the device is locked

lock.ref

String

The reference url for the lock

lock.lock_reason[]

Array

List containing all reasons for the device lock. See lock reason for possible values.

push_address

String

The push address for the device, this address is used when sending push to the device using FCM or APNS. Introduced in Encap 3.11

recoveries

Array

List of all recoveries for the device. See recovery object for details. Introduced in Encap 3.13

recovery_lock

Boolean

Explicit setting for the device to lock/unlock recovery. Introduced in Encap 3.13

attestation

Object

Attestation object that contains details for all the attestations performed for the device. See attestation object for details.

3.6.2. Get device details

GET /api/smart-device/v1/devices/{deviceId}

Get device details

Returns

Returns an device object if a valid identifier was provided, otherwise returns an error.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 01f1d41a-781f-44c5-8f6d-f85a0c6023b6
Content-Type: application/json
Content-Length: 1428

{
  "id" : "79735c4b-5def-43f3-9e60-3edc5a3d75ae",
  "application_id" : "encap",
  "current_client_api_version" : "3.18.0",
  "activated_client_api_version" : "3.18.0",
  "activated_encap_release" : "R_3_11",
  "device_hash" : "Xsx6d7bmhh9ovUvhqp5KLOs480%2FWCq3bq9%2FC0apC4TU%3D",
  "salt_hash" : "ap7cmrQQTc0zb5aCPgXV0JxvrFeOO6CguQklentLMsc%3D",
  "push_address" : "ap7cmrQQTc0zb5aCPgXV0JxvrFeOO6CguQklentLMsc",
  "operating_system_type" : "iOS",
  "activated_authentication_methods" : [ "DEVICE", "DEVICE:PIN" ],
  "activation_time" : "2017-04-05T12:23:00.000UTC",
  "last_used_time" : "2023-09-28T11:29:37.098UTC",
  "lock" : {
    "ref" : "/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/lock",
    "lock_reason" : [ "DEVICE_VERIFICATION_FAILED", "LOCKED_BY_ADMIN" ]
  },
  "attestation" : {
    "safety_net_status" : "VERIFIED",
    "safety_net_date" : "2023-09-28T11:29:37.098UTC",
    "app_attest_status" : "VERIFIED",
    "app_attest_date" : "2023-09-28T11:29:37.098UTC",
    "play_integrity_status" : "VERIFIED",
    "play_integrity_date" : "2023-09-28T11:29:37.098UTC"
  },
  "recoveries" : [ {
    "recovery_id" : "c44ec219-2b4b-45c9-a805-c3874aa33451",
    "recovery_method" : "CLOUD_BACKUP",
    "recovery_status" : "ACTIVATED",
    "created_date" : "2023-09-28T11:29:37.098UTC",
    "updated_date" : "2023-09-28T11:29:37.098UTC",
    "recovered_date" : "2023-09-28T11:29:37.098UTC"
  } ],
  "recovery_lock" : false
}

3.6.3. Deactivate device

DELETE /api/smart-device/v1/devices/{deviceId}

Disable authentication credentials for this device. This includes deleting device credentials.

Returns

Returns 204 No Content if a valid identifier was provided and the device was deleted. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: b5da07ef-9a0f-4cd7-882c-e597be047e91

3.7. Device Sessions

All operations for a given enrollment creates a session. A list of all sessions for a device can be retrieved including some meta info for each session. For a more detailed description of a session follow the detailed link in the meta info for that session. For sessions with an operation type without a REST API, the detail link is omitted.

3.7.1. The session object

Field Type Description

session_id

UUID

The UUID for the session

ref

String

Link to authentication object for the session

purpose

String

The purpose of the session. See session purpose for details.

state

String

The state of the session

session_created_on

String

The date for when the session was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

session_expires_on

String

The date for when the session expires. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

offline

Boolean

True if this is an offline authentication session

client_only

Boolean

True if the session was run in client only mode

device_id

String

The device ID that owns the session

3.7.2. Get sessions for device

GET /api/smart-device/v1/device/{deviceId}/sessions?limit=10&offset=0
Returns

Returns a pagination object with a list of session objects if a valid identifier was provided, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/sessions?limit=5' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 2d2ecc59-e8aa-4bf2-8fb1-6b87e31ddcdc
Content-Type: application/json
Content-Length: 1488

{
  "previous" : "/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/sessions?limit=5&offset=e26f89f6-e921-42eb-b1d8-ac5c1d2201dd",
  "next" : "/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/sessions?limit=5&offset=1f73d6d7-b3a4-460c-87fe-3fa7ef5d661e",
  "limit" : 5,
  "items" : [ {
    "session_id" : "93053845-c090-4496-9539-8156da7758f9",
    "device_id" : "79735c4b-5def-43f3-9e60-3edc5a3d75ae",
    "ref" : "/enrollments/93053845-c090-4496-9539-8156da7758f9",
    "purpose" : "ACTIVATION",
    "state" : "SUCCESS",
    "client_only" : false,
    "session_created_on" : "2023-09-28T11:29:37.722UTC",
    "session_expires_on" : "2023-09-28T11:29:37.722UTC",
    "offline" : false
  }, {
    "session_id" : "3a384137-74b2-4d90-ae41-9ad3fb8613d2",
    "device_id" : "79735c4b-5def-43f3-9e60-3edc5a3d75ae",
    "ref" : "/authentications/3a384137-74b2-4d90-ae41-9ad3fb8613d2",
    "purpose" : "AUTHENTICATION",
    "state" : "IN_PROGRESS",
    "client_only" : false,
    "session_created_on" : "2023-09-28T11:29:37.722UTC",
    "session_expires_on" : "2023-09-28T11:29:37.722UTC",
    "offline" : false
  }, {
    "session_id" : "1ff43f4a-5009-491f-bd58-5ad738fc08fe",
    "device_id" : "79735c4b-5def-43f3-9e60-3edc5a3d75ae",
    "purpose" : "DELETE_RECOVERY",
    "state" : "IN_PROGRESS",
    "client_only" : false,
    "session_created_on" : "2023-09-28T11:29:37.722UTC",
    "session_expires_on" : "2023-09-28T11:29:37.722UTC",
    "offline" : false
  } ]
}

3.8. Sessions for multiple devices

Retrieve a list of the latest sessions for a set of devices, including limited meta info for each session. Follow the reference link in the meta info for more detailed description of the session and its meta info. For sessions with an operation type without a REST API, the reference link is omitted. The number of devices to query is limited to 100.

3.8.1. Get sessions for multiple devices

GET /api/smart-device/v1/sessions/sessions?deviceId={deviceId1}&deviceId={deviceId2}&limit=10&offset=0
Returns

Returns a pagination object with a list of session objects if all identifiers are valid, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/sessions?deviceId=e1046ce5-ec79-4c1f-a87f-94795327c5e8&deviceId=ae67b4d3-ec25-4f99-a689-ec0d9c126f27&limit=4' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 1d1983e2-dc95-4d0b-8bfd-93b261326d82
Content-Type: application/json
Content-Length: 2057

{
  "previous" : "/smart-device/v1/sessions?deviceId=e1046ce5-ec79-4c1f-a87f-94795327c5e8&deviceId=ae67b4d3-ec25-4f99-a689-ec0d9c126f27&limit=4&offset=0a9d9bbf-3f7b-43ac-a7ca-5d6a7ce96d5b",
  "next" : "/smart-device/v1/sessions?deviceId=e1046ce5-ec79-4c1f-a87f-94795327c5e8&deviceId=ae67b4d3-ec25-4f99-a689-ec0d9c126f27&limit=4&offset=0b094904-9135-4762-a993-77b61c90883b",
  "limit" : 4,
  "items" : [ {
    "session_id" : "4dccb5c4-f16f-4900-a34b-4cbfc067a9c5",
    "device_id" : "e1046ce5-ec79-4c1f-a87f-94795327c5e8",
    "ref" : "/enrollments/4dccb5c4-f16f-4900-a34b-4cbfc067a9c5",
    "purpose" : "ACTIVATION",
    "state" : "SUCCESS",
    "client_only" : false,
    "session_created_on" : "2023-09-28T11:29:40.924UTC",
    "session_expires_on" : "2023-09-28T11:29:40.924UTC",
    "offline" : false
  }, {
    "session_id" : "18ad3e6a-a0d8-442e-98db-af081ff9b588",
    "device_id" : "e1046ce5-ec79-4c1f-a87f-94795327c5e8",
    "ref" : "/authentications/18ad3e6a-a0d8-442e-98db-af081ff9b588",
    "purpose" : "AUTHENTICATION",
    "state" : "IN_PROGRESS",
    "client_only" : false,
    "session_created_on" : "2023-09-28T11:29:40.924UTC",
    "session_expires_on" : "2023-09-28T11:29:40.924UTC",
    "offline" : false
  }, {
    "session_id" : "c8b397d6-2535-4325-b369-7c6e46de89ca",
    "device_id" : "ae67b4d3-ec25-4f99-a689-ec0d9c126f27",
    "ref" : "/enrollments/c8b397d6-2535-4325-b369-7c6e46de89ca",
    "purpose" : "ACTIVATION",
    "state" : "SUCCESS",
    "client_only" : false,
    "session_created_on" : "2023-09-28T11:29:40.924UTC",
    "session_expires_on" : "2023-09-28T11:29:40.924UTC",
    "offline" : false
  }, {
    "session_id" : "1c8a93c1-af6e-4362-aae7-b30ca118f0d3",
    "device_id" : "ae67b4d3-ec25-4f99-a689-ec0d9c126f27",
    "ref" : "/authentications/1c8a93c1-af6e-4362-aae7-b30ca118f0d3",
    "purpose" : "AUTHENTICATION",
    "state" : "IN_PROGRESS",
    "client_only" : false,
    "session_created_on" : "2023-09-28T11:29:40.924UTC",
    "session_expires_on" : "2023-09-28T11:29:40.924UTC",
    "offline" : false
  } ]
}

3.9. Device Lock

Every device can have a lock. A lock can be created through this API or as a result of various other processes.

3.9.1. The lock object

Field Type Description

id

UUID

The UUID for the device

lock

Object

An lock object containing lock details

lock.ref

String

The reference url for the lock

lock.lock_reason[]

Array

List containing all reasons for the device lock. See lock reason for possible values.

3.9.2. Lock device

POST /api/smart-device/v1/devices/{deviceId}/lock

A device is locked by creating a lock on the device-id.

Returns

Returns a lock object if lock succeeded. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/lock' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 82a69793-9dd1-4e7e-893d-988d30bd393b
Content-Type: application/json
Content-Length: 207

{
  "id" : "79735c4b-5def-43f3-9e60-3edc5a3d75ae",
  "lock" : {
    "ref" : "/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/lock",
    "lock_reason" : [ "DEVICE_VERIFICATION_FAILED", "LOCKED_BY_ADMIN" ]
  }
}

3.9.3. Get lock status for device

GET /api/smart-device/v1/devices/{deviceId}/lock

Looking at the lock for a device-id will tell why the device was locked.

Returns

Returns a lock object if a valid identifier was provided and a lock exist for it. Returns 409 Conflict if no lock exists. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/lock' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 7e76f003-b273-4e0c-beba-91eee6e21a93
Content-Type: application/json
Content-Length: 207

{
  "id" : "79735c4b-5def-43f3-9e60-3edc5a3d75ae",
  "lock" : {
    "ref" : "/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/lock",
    "lock_reason" : [ "DEVICE_VERIFICATION_FAILED", "LOCKED_BY_ADMIN" ]
  }
}

3.9.4. Unlock device

DELETE /api/smart-device/v1/devices/{deviceId}/lock

A device is unlocked by removing the lock from the device-id.

Returns

Returns 204 No Content if a valid identifier was provided and lock was removed. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/lock' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: 904f4e18-327c-4206-9d24-d54b2318a880

3.10. Lock authentication method

In addition to devices, every authentication method can have a lock. A locked offline-method does not result in the entire device being locked. While locking an online-method will lock the device and make it unable to perform any operation.

See authentication methods for possible values for authMethod (Variant 1).

3.10.1. Lock authentication method

POST /api/smart-device/v1/devices/{deviceId}/authmethods/{authMethod}/lock

Locks the specified authentication method for the device.

Returns

Returns an empty response if the operation succeeds. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/02c0ffab-636d-48fc-a5c3-599557f94141/authmethods/OFFLINE_PIN/lock' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: 2a60db75-c5a2-44e2-b15b-f285ec178b2c

3.10.2. Get lock status for device

GET /api/smart-device/v1/devices/{deviceId}/authmethods/{authMethod}/lock

Fetches the lock status of the specified authentication method.

Returns

Returns the lock status of the authentication method.

Field Type Description

lock_status

String

Lock status of this auth method

Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/c05de289-e3c2-4027-ae7e-c5015cf29ad0/authmethods/OFFLINE_PIN/lock' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 5e6d8db7-6b87-468b-b931-7819f728d984
Content-Type: application/json
Content-Length: 39

{
  "lock_status" : "LOCKED_BY_ADMIN"
}

3.10.3. Unlock authentication method

DELETE /api/smart-device/v1/devices/{deviceId}/authmethods/{authMethod}/lock

Removes the lock from the authentication method.

Returns

Returns 204 No Content if successful. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/a22e5c7c-4d09-40d1-bf72-3b865f38cc58/authmethods/OFFLINE_PIN/lock' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: fd05f73e-f35b-4dec-8e42-4183c0b99b11

3.11. Account Recovery

Account Recovery adds support for recovering a device after it being replaced, lost or stolen. With Account Recovery the user can add recovery for his device that is protected with a user created recovery code (PIN). The recovery secret is stored in the cloud backup (Google Cloud or Apple iCloud) provided that the user has enabled backup of his apps. The feature allows the user to recover the app on another device while the service provider reference (device_id) remains unchanged.

3.11.1. The perform recovery session object

Field Type Description

id

UUID

The UUID for the recovery session

application_id

String

The application ID for the device

device_id

UUID

The UUID for the device

session_created_time

String

The time for when the session was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

session_expiry_time

String

The time for when the session will expire. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

purpose

String

The purpose of the session. See session purpose for details.

activated_authentication_methods

Array

List of activated authentication methods (Variant 2). See authentication methods for possible values

risk_attributes

Array

List that contains name and value for all risk attributes. See risk_attributes object for details.

location

Object

Location object that contains location details, see location object for details.

session_status

Object

Status object that contains status details of the session. See session_status object for details.

attestation

Object

Attestation object that contains details for all the attestations performed for the device. See attestation object for details.

3.11.2. Get perform recovery details

GET /api/smart-device/v1/perform-recoveries/{session_id}

Get the session details after performing a recovery. The session details let you know the state of the recovery, and if finished it gives you access to risk data and all other attributes created as part of the recovery process. You can find the session_id by looking at the device sessions with the correct session purpose.

Returns

Returns an perform recovery object if a valid session identifier was provided, otherwise returns an error.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/perform-recoveries/1ee767a1-5cf9-4b00-9f8e-156c524deecf' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 3872bb50-74c9-4450-8e3c-5dd756b2e65e
Content-Type: application/json
Content-Length: 1435

{
  "id" : "1ee767a1-5cf9-4b00-9f8e-156c524deecf",
  "application_id" : "encap",
  "device_id" : "c489014d-86aa-4237-868b-c4e87ba91957",
  "session_created_time" : "2023-09-28T11:29:40.739UTC",
  "session_expiry_time" : "2023-09-28T13:29:40.739UTC",
  "activated_authentication_methods" : [ "DEVICE", "DEVICE:PIN", "DEVICE:TOUCH_ID" ],
  "location" : {
    "accuracy" : "0.564",
    "altitude" : "76.2352.3563",
    "latitude" : "12.34234.143",
    "longitude" : "32.24314.1431"
  },
  "risk_attributes" : [ {
    "name" : "is_debuggable",
    "value" : "true"
  }, {
    "name" : "is_unknown_sources_enabled",
    "value" : "true"
  }, {
    "name" : "is_debugger_connected",
    "value" : "true"
  }, {
    "name" : "input_method",
    "value" : "input"
  }, {
    "name" : "is_emulator",
    "value" : "true"
  }, {
    "name" : "operating_system_version",
    "value" : "2.3"
  }, {
    "name" : "client_side_ip",
    "value" : "[\"192.168.0.1\"]"
  } ],
  "session_status" : {
    "status" : "IN_PROGRESS",
    "description" : "Operation is in progress",
    "state" : "IN_PROGRESS"
  },
  "attestation" : {
    "safety_net_status" : "VERIFIED",
    "safety_net_date" : "2023-09-28T11:29:40.738UTC",
    "app_attest_status" : "VERIFIED",
    "app_attest_date" : "2023-09-28T11:29:40.738UTC",
    "play_integrity_status" : "VERIFIED",
    "play_integrity_date" : "2023-09-28T11:29:40.738UTC"
  },
  "purpose" : "PERFORM_RECOVERY"
}

3.12. Recovery Lock for device

The Account Recovery feature is enabled in the application configuration and can by default be used by all devices. The feature can be disabled for an explicit device by setting the recovery lock using this API, or by setting the recovery lock field when doing a new enrollment.

The recovery lock is by default set to false and if set to true the device will not be able to perform any recovery operations.

3.12.1. The recovery lock object

Field Type Description

recovery_lock

Boolean

Explicit setting for the device to lock/unlock recovery. Introduced in Encap 3.13

3.12.2. Get recovery lock status for device

GET /api/smart-device/v1/devices/{deviceId}/recovery-lock

Check if recovery is locked for the given device

Returns

Returns a recovery object if a valid device identifier is provided. Returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/recovery-lock' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 1c7ecdec-7cba-4155-b37d-e47f13f4412e
Content-Type: application/json
Content-Length: 29

{
  "recovery_lock" : false
}

3.12.3. Change recovery lock

PUT /api/smart-device/v1/devices/{deviceId}/recovery-lock

Lock/unlock recovery for the given device

Returns

Returns 202 Accepted if setting the recovery lock is successful. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/recovery-lock' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "recovery_lock" : "true"
}'
Example response
HTTP/1.1 202 Accepted
X-Correlation-UUID: 52738fc1-d94d-4943-9b4b-e31a045ff3da
Content-Type: application/json
Content-Length: 28

{
  "recovery_lock" : true
}

3.13. Override Geofencing settings for device

The Geofencing feature is configured in the application configuration and by default the settings therein applies to all devices. The geofencing configuration for authentication operations can be overridden for an explicit device using this API. By overriding the configuration, the device will have a fully independent configuration (for authentication operations), and the settings in application configuration will no longer apply.

3.13.1. The geofencing object

Field Type Description

mode

String

Geofencing enforcement mode (OFF/OPTIONAL/REQUIRED)

allowed_continents

String

Comma separated list of continents in which authentication is allowed (AF/NA/OC/AN/AS/EU/SA)

allowed_countries

String

Comma separated list of countries in which authentication is allowed (in addition to allowed continents). ISO 3166-1 alpha-2 standard.

denied_countries

String

Comma separated list of countries in which authentication is not allowed (exception from allowed continents). ISO 3166-1 alpha-2 standard.

3.13.2. Get geofencing configuration for device

GET /api/smart-device/v1/devices/{deviceId}/geofencing

Retrieve geofencing configuration for the given device

Returns

Returns a geofencing object if a valid device identifier is provided. Returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/geofencing' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 1c45c818-b317-4f4e-9937-237c78149f2c
Content-Type: application/json
Content-Length: 115

{
  "mode" : "OPTIONAL",
  "allowed_continents" : "EU",
  "allowed_countries" : "CT",
  "denied_countries" : "RU"
}

3.13.3. Update geofencing configuration for device

PUT /api/smart-device/v1/devices/{deviceId}/geofencing

Update geofencing configuration for the given device

Returns

Returns 202 Accepted together with the updated geofencing object if the update is successful. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/geofencing' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "mode" : "OPTIONAL",
  "allowed_continents" : "EU",
  "allowed_countries" : "CT",
  "denied_countries" : "RU"
}'
Example response
HTTP/1.1 202 Accepted
X-Correlation-UUID: 022ccdbe-090c-45bb-bd00-6512ce937109
Content-Type: application/json
Content-Length: 115

{
  "mode" : "OPTIONAL",
  "allowed_continents" : "EU",
  "allowed_countries" : "CT",
  "denied_countries" : "RU"
}

3.13.4. Delete geofencing configuration for device

DELETE /api/smart-device/v1/devices/{deviceId}/geofencing

Delete geofencing configuration for the given device

Returns

Returns 204 No Content if successful. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/smart-device/v1/devices/79735c4b-5def-43f3-9e60-3edc5a3d75ae/geofencing' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: e09b74fa-f3ab-4dd4-ad0b-d34e5edd11dc

4. Admin API

4.1. Server status

Provides a health check of the Encap instances. If called unauthenticated only a overall status is provided.

4.1.1. The status object

Field Type Description

success

Boolean

Indicates if the API is in a "healthy" state

created_on

String

An RFC 3339 formatted date and time in UTC

dependencies

Array

Array of underlying dependencies and their status. Only included if request is authenticated

dependencies[].success

Boolean

Indicates if this dependency is in a "healthy" state

dependencies[].request_time

Number

Time in milliseconds it took to check this dependency

dependencies[].resource

String

Name of dependency

4.1.2. Get API status

GET /api/admin/v1/status
Example request
$ curl 'http://localhost:8080/api/admin/v1/status' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 12e81cd9-bc31-4ad9-8aec-7f26af11739e
Content-Type: application/json
Content-Length: 179

{
  "success" : true,
  "created_on" : "2023-09-28T11:29:41.133UTC",
  "dependencies" : [ {
    "resource" : "Core database",
    "success" : true,
    "request_time" : 10
  } ]
}
Example response if unauthenticated
HTTP/1.1 200 OK
X-Correlation-UUID: a0992480-9a7c-4602-b8b3-646f5b098ddd
Content-Type: application/json
Content-Length: 69

{
  "success" : true,
  "created_on" : "2023-09-28T11:29:41.089UTC"
}

4.2. Application Configuration

Operations on Application Configuration.

Consult 3.1.2 - ApplicationID configurations in the Encap Server Administration Manual for information about this topic.

All operations on this endpoint requires authentication. See the rest api authentication section

4.2.1. The application configuration object

Field Type Description

app_id

String

The logical name of the application configuration

uuid

UUID

The unique ID of this application configuration registration. This value is central to these APIs

apns_uuid

UUID

Reference to the APNS push certificate or token.

app_name

String

The human readable name for the application configuration

configuration

Object

The application configuration parameters

4.2.2. The configuration object

This object contains the configuration parameters and their value

Parameter Description Allowed values Default

ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY

Lower limit for how guessable the activation code is. Given as 1 in x where this param represents x. The server calculates the actual value based on the cardinality of the activation code type, the activation code length and the number of active activations. If this value is below 1 in x with x as defined here the server prevents the new activation from starting. It is not possible to set this lower than 1 in 1,000.

The higher the number the lower the probability is of guessing the activation code.

To increase the number of concurrently active activation supported increase the ACTIVATION_CODE_LENGTH or choose a ACTIVATION_CODE_TYPE with greater cardinality.

E.g.

ACTIVATION_CODE_LENGTH = 4

ACTIVATION_CODE_TYPE = NUMERIC

This gives 10,000 possible activation codes. With 1 activation in progress the chance of guessing the activation code is 1 in 10,000. With 10 concurrent activations we have a chance of guessing a valid code reduced to 1 in 1,000 (10,000 / 10 = 1,000). If an 11th activation session starts before any of the others finish it will fail the ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY check as this brings the chance below 1 in 1,000 (10,000 / 11 = 909).

1000 .. MAXINT

1000

ACTIVATION_CODE_LENGTH

The length in characters of the activation code that should be generated.

4 .. MAXINT

6

ACTIVATION_CODE_TYPE

The type of characters that can be used during the generation of the activation code.

ALPHA, ALPHANUMERIC, ANY, NUMERIC

NUMERIC

ALLOWED_AUTH_METHODS

Comma separated list of allowed authentication methods. Determines which auth methods can be activated and used for authentication

See authentication methods for applicable auth methods (Variant 1)

DEVICE, DEVICE:PIN

ALLOWED_AUTH_METHODS_FOR_AUTH_AND_ACTIVATE

Comma separated list of allowed authentication methods for activation of a new auth-method. Determines which auth methods can be used to authenticate during activation of a new auth method.

The value(s) here must be present in the ALLOWED_AUTH_METHODS parameter. Offline authentication methods can not be used here.

See authentication methods for applicable auth methods (Variant 1)

DEVICE:PIN

AMOUNT_FAILURES_ALLOWED

The grace amount of failed DEVICE_PIN (or offline) authentications for any client before they are locked out.

0..MAXINT

3

APN_CONFIG

The APN server configuration that defines where to reach the APNs.

PRODUCTION, SANDBOX

PRODUCTION

APN_EXPIRY

The amount of time that a message dispatched to the APN service should remain valid. If the APNs cannot deliver the message before this time expires, the message will be discarded and will never arrive.

0..MAXINT

0

APNS_BUNDLE_ID

Apples bundle id for the application. Used as topic on the push message sent to APNs, required when using APNs provider token for sending push messages.

String

APNS_NOTIFICATION_SOUND_ENABLED

Enable notification sound for push messages to iOS devices.

true, false

false

APNS_TIME_SENSITIVE_INTERRUPTION_LEVEL_ENABLED

Sets the interruption level for push messages to iOS devices to "time-sensitive".

true, false

false

CLIENT_ONLY_ALLOWED

True if the client is allowed to perform client-only activations and authentications.

A client-only operation is one that is not initiated by a service provider request.

true, false

true

ENCAP_API_BLACKLIST_ANDROID

Android SDK API versions to blacklist (and reject). See the android configuration chapter in the server manual for smart device for details.

Comma separated semantic version, ex: "3.5.3, 3.6.8"

null

ENCAP_API_BLACKLIST_IOS

IOS SDK API versions to blacklist (and reject). See the ios configuration chapter in the server manual for smart device for details.

Comma separated semantic version, ex: "3.5.3, 3.6.8"

null

ENABLED_RISK_DATA

Comma separated list of which risk data to store, or ALL if all the available risk data should be stored. Details for risk data is specified in the EncapAuthenticationStateless document and in the REST documentation.

See config attribute column in risk_attributes for available values.

Value 'ALL' will enable all risk attributes.

Default value is empty which represents that no risk data is enabled.

FIREBASE_DATABASE_URL

Firebase Cloud Messaging. The URL of your Firebase database (as shown in the Firebase project settings).

String

FIREBASE_SERVICE_ACCOUNT

Firebase Cloud Messaging. The contents of the serviceAccount.json (credentials file) for your Firebase Cloud Messaging project.

String

FIREBASE_TIME_TO_LIVE

Firebase Cloud Messaging. Maximum lifespan of the message in milliseconds. The default value is 0. This means deliver “now or never”. FCM guarantees best effort for messages with this lifespan.

0..MAXINT

0

HWKEY_VALIDATION_STRATEGY

What to do if validating the signature based on the hardware supported keys. SUPPORTED means that clients who register the public key in a healthy manner during Registration, will fail Authentication if they fail to provide a signature based on the Hardware Supported key.

If this flag is RISK_PARAMS, the failing signature will only result in risk parameters on authentication and will not fail the authentication.

SUPPORTED

RISK_PARAMS

SUPPORTED

SESSION_EXPIRY

The amount of time (in milliseconds) that a new client session remains valid for. After this time has elapsed, the session can no longer be used for any operations

1..MAXINT

300000

MAXIMUM_SESSION_EXPIRY

The maximum amount of time (in milliseconds) the sessionExpiry can be set to.

1..MAXINT

300000

MINIMUM_REQUIRED_ENCAP_API_VERSION_ANDROID

What Android client SDK version should be allowed. This can be used to narrow (not extend) the SDK version. Example is if the server minimum is "3.5.0", and someone wants to only to allow "3.6.0" -clients, this can be achieved here. But putting "3.3.0" will not have any effect.

Semantic version, ex: "3.7.0"

null

MINIMUM_REQUIRED_ENCAP_API_VERSION_IOS

The same as MINIMUM_REQUIRED_ENCAP_API_VERSION_ANDROID, but applies to iOS clients.

Semantic version, ex: "3.7.0"

null

NATIVE_PUSH_ENABLED

Enable the server to send push messages with Fire Cloud Messaging or Apple APNS

true, false

false

RECOVERY_ENABLED

Enable users to set up recovery with an alternative set of user credentials

true, false

false

RECOVERY_CODE_MIN_LENGTH

The minimum number of characters for the recovery PIN. Note: This is a hint to the client and not enforced by the server.

0..MAXINT

6

RECOVERY_CODE_MAX_LENGTH

The maximum number of characters for the recovery PIN. Note: This is a hint to the client and not enforced by the server.

0..MAXINT

50

RECOVERY_CODE_FORMAT

The type of characters that can be used in the recovery PIN. Note: This is a hint to the client and not enforced by the server.

ALPHA, ALPHANUMERIC, ANY, NUMERIC

NUMERIC

RECOVERY_CODE_AMOUNT_FAILURES_ALLOWED

The grace amount of failed recovery code attempts for any client before the recovery for the client is locked.

0..MAXINT

3

AUTHORIZATION_TOKEN_TIMEOUT

Authorization token timeout in milliseconds. After this time, the token will not be valid anymore.

0..MAXINT

300000

GEOFENCING_ACTIVATION_MODE

Geofencing mode for activation.

REQUIRED: Device location check is performed. If the location is not part of the allowed regions or the location check fails, activation request will fail.

OPTIONAL: Device location check is performed. If the location is not part of the allowed regions or the location check fails, activation request will be performed and Service Provider will be notified about it via the API.

OFF: Device location check is not performed.

REQUIRED, OPTIONAL, OFF

OFF

GEOFENCING_ACTIVATION_ALLOWED_CONTINENTS

List of continents in which activation is allowed.

2 letter continent codes (AF/NA/OC/AN/AS/EU/SA), in a comma separated list.

GEOFENCING_ACTIVATION_ALLOWED_COUNTRIES

List of countries in which activation is allowed in addition to allowed continents.

Country codes following ISO 3166-1 alpha-2 standard, in a comma separated list.

GEOFENCING_ACTIVATION_DENIED_COUNTRIES

List of countries in which activation is not allowed (exception from allowed continents).

Country codes following ISO 3166-1 alpha-2 standard, in a comma separated list.

GEOFENCING_AUTHENTICATION_MODE

Geofencing mode for authentication.

REQUIRED: Device location check is performed. If the location is not part of the allowed regions or the location check fails, authentication request will fail and Service Provider will be notified about it via the API.

OPTIONAL: Device location check is performed. If the location is not part of the allowed regions or the location check fails, authentication request will be performed.

OFF: Device location check is not performed.

REQUIRED, OPTIONAL, OFF

OFF

GEOFENCING_AUTHENTICATION_ALLOWED_CONTINENTS

List of continents in which authentication is allowed.

2 letter continent codes (AF/NA/OC/AN/AS/EU/SA), in a comma separated list.

GEOFENCING_AUTHENTICATION_ALLOWED_COUNTRIES

List of countries in which authentication is allowed in addition to allowed continents.

Country codes following ISO 3166-1 alpha-2 standard, in a comma separated list.

GEOFENCING_AUTHENTICATION_DENIED_COUNTRIES

List of countries in which authentication is not allowed (exception from allowed continents).

Country codes following ISO 3166-1 alpha-2 standard, in a comma separated list.

GEOFENCING_TIMEOUT

Timeout allowed for the client to wait for location and perform reverse geolocation lookup (if the timeout is exceeded, the client will continue without country).

0..MAXINT

10000

EVENT_CALLBACK_EVENTS

Comma separated list of events that shall trigger a REST callback to the service provider url configured. You can also filter events per API to have even more control of when a callback should be issued.

Allowed events: See event-callback-events
Allowed APIs: See event-callback-apis

When not specifying an API the callback for the event will be sent regardless of API.

e.g. DEVICE_LOCKED, DEVICE_DEACTIVATED:[REST]
This triggers callback for DEVICE_LOCKED (all apis), and for DEVICE_DEACTIVATED when calls are received from REST.

Format specification: <event-type-1>[:< [api-1|api-2|…​] >], <event-type-2>[:< [api-1|api-2|…​] >]

Allowed events: See event-callback-events

EVENT_CALLBACK_URL

The URL that should receive callbacks in case any callback events have been configured for this app-config.

String

CLIENT_DEBUG_DATA_ENABLED_OS_TYPES

Comma separated list of operating system types (iOS/Android) for enabling client debug data. It might be set to one of the platforms, or both.

It is empty by default, hence no client debug data is sent to the server.

IOS, ANDROID

PIN_CODE_LENGTH

The minimum length in characters of the PIN. Note: This is a hint to the client and not enforced by the server (but enforced in the client SDK).

1..MAXINT

4

MAX_PIN_CODE_LENGTH

The maximum length in characters of the PIN. Note: This is a hint to the client and not enforced by the server (but enforced in the client SDK).

1..MAXINT

4

PIN_CODE_TYPE

The type of characters that can be used in the PIN. Note: This is a hint to the client and not enforced by the server.

ANY, NUMERIC, ALPHA, ALPHANUMERIC

NUMERIC

TOKEN_TYPE

The type of token to respond with to the client when one is requested.

Note: The client can request a different type of token during the authentication operation.

This setting indicates the default type to use when the client doesn’t specify one.

SAML1, SAML2

SAML2

URL_SCHEME

The scheme part of URLs generated for push methods that require a URL. This is the URL Scheme that the client is configured to be activated with.

A valid URL scheme

encap

ATTESTATION_ANDROID_SAFETYNET_MODE

SafetyNet Attestation mode.

REQUIRED: SafetyNet attestation is preformed. If attestation fails activation/authentication request will fail.

OPTIONAL: SafetyNet attestation is preformed. If attestation fails activation/authentication request will not fail and a new attestation is performed on the next request.

OFF: SafetyNet attestation is not preformed.

The SafetyNet API has been deprecated by Google and is now replaced by the Play Integrity API which is supported from Encap 3.17.

REQUIRED, OPTIONAL, OFF

OFF

ATTESTATION_ANDROID_SAFETYNET_INTEGRITY_CHECK_MODE

SafetyNet Attestation integrity mode. Defines the strictness when interpreting the SafetyNet attestation. Required if ATTESTATION_ANDROID_SAFETYNET_MODE is REQUIRED or OPTIONAL.

LEAN: Requires basicIntegrity integrity to be true.

STRICT: Requires both ctsProfileMatch and basicIntegrity to be true.

LEAN, STRICT

ATTESTATION_ANDROID_SAFETYNET_TIMEOUT

SafetyNet Attestation timeout, in milliseconds, the timeout for a request made to SafetyNet. Required if ATTESTATION_ANDROID_SAFETYNET_MODE is REQUIRED or OPTIONAL.

1..MAXINT

ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE

Play Integrity attestation mode.

REQUIRED: Play Integrity attestation is preformed. If attestation fails activation/authentication request will fail.

OPTIONAL: Play Integrity attestation is preformed. If attestation fails activation/authentication request will not fail and a new attestation is performed on the next request.

OFF: Play Integrity attestation is not preformed.

Play Integrity attestation was introduced in version 3.17 and will only be applicable for clients 3.17 or newer.

REQUIRED, OPTIONAL, OFF

OFF

ATTESTATION_ANDROID_PLAY_INTEGRITY_TIMEOUT

Play Integrity attestation timeout, in milliseconds, the timeout for a request made to Play Integrity. Required if ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE is REQUIRED or OPTIONAL.

1..MAXINT

ATTESTATION_ANDROID_PLAY_INTEGRITY_DECRYPTION_KEY

Play Integrity attestation decryption key, used to decrypt the integrity token. Required if ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE is REQUIRED or OPTIONAL.

Base64

ATTESTATION_ANDROID_PLAY_INTEGRITY_VERIFICATION_KEY

Play Integrity attestation verification key, used to validate the integrity token. Required if ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE is REQUIRED or OPTIONAL.

Base64

ATTESTATION_ANDROID_PACKAGE_NAME

Play Integrity/SafetyNet attestation, the APK package name. Required if ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE or ATTESTATION_ANDROID_SAFETYNET_MODE is REQUIRED or OPTIONAL.

String

ATTESTATION_ANDROID_CERTIFICATE_DIGEST

SafetyNet Attestation, the APK certificate SHA-256 digest. Base64 encoded SHA-256. Required if ATTESTATION_ANDROID_SAFETYNET_MODE is REQUIRED or OPTIONAL.

Base64

ATTESTATION_IOS_APP_ATTEST_MODE

iOS Attestation mode when using Apple App Attest.

REQUIRED: App attestation enabled. If attestation fails the activation/authentication request will fail. Note that devices running versions of iOS older than 14 will always fail if the mode is set to REQUIRED, due to requirements by the Apple App Attest API.

OPTIONAL: App attestation enabled. Even if the attestation fails, the activation/authentication request will succeed, and a new attestation will be performed on the next request. The status can be seen in the response object.

OFF: App attestation disabled.

REQUIRED, OPTIONAL, OFF

OFF

ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT

The environment for an app that uses the App Attest service to validate itself.

DEVELOPMENT, PRODUCTION

PRODUCTION

ATTESTATION_IOS_APP_ATTEST_TIMEOUT

iOS app attestation timeout, after this time, in milliseconds, the attestation request will time out.

1..MAXINT

20000

ATTESTATION_IOS_APP_ATTEST_APP_ID

App ID which is a concatenation of a 10-digit team identifier, a period, and the app’s CFBundleIdentifier value. Required when using Apple App Attest service.

String

CLIENT_REQUEST_TIME_VALIDATION_ENABLED

Validation of client request time to be able to block client requests coming in to the server out of order. Recommending to set as enabled, and should only be disabled in case of an error or for debugging purposes.

true, false

true

CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD

Perform validation of the client request time if the new request is within the threshold time of the last one. Recommended to set equal or higher to the load balancer idle timeout.

1..MAXINT

300000

OFFLINE_OTP_LENGTH

Length of one time password. Required if any of the OTP authentication methods are available.

4..9

4.2.3. Create application configuration

POST /api/admin/v1/appconfig

Creates a new application configuration. Returns the application configuration object.

Arguments
Path Type Required Description

app_id

String

Yes

The logical name of the application configuration

apns_uuid

UUID

No

The UUID of the APNs push certificate or token used. Required if NATIVE_PUSH_ENABLED is true.

app_name

String

No

The human readable name for the application configuration

configuration

Object

Yes

The application configuration parameters. Required to contain at least one configuration.
Returns

Returns an application configuration object if request is process successfully. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/admin/v1/appconfig/' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "app_id" : "some-new-app",
  "apns_uuid" : "cefdaccc-efc0-41a3-80a8-5de6faf2c053",
  "app_name" : "AppName",
  "configuration" : {
    "CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD" : "300000",
    "RECOVERY_CODE_MIN_LENGTH" : "6",
    "GEOFENCING_ACTIVATION_MODE" : "OFF",
    "ATTESTATION_IOS_APP_ATTEST_TIMEOUT" : "20000",
    "ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT" : "PRODUCTION",
    "RECOVERY_CODE_MAX_LENGTH" : "50",
    "ALLOWED_AUTH_METHODS" : "DEVICE, DEVICE:PIN",
    "HWKEY_VALIDATION_STRATEGY" : "SUPPORTED",
    "SESSION_EXPIRY" : "300000",
    "MAXIMUM_SESSION_EXPIRY" : "300000",
    "RECOVERY_ENABLED" : "false",
    "RECOVERY_CODE_FORMAT" : "NUMERIC",
    "MAX_PIN_CODE_LENGTH" : "6",
    "TOKEN_TYPE" : "SAML2",
    "AUTHORIZATION_TOKEN_TIMEOUT" : "300000",
    "URL_SCHEME" : "encap",
    "CLIENT_ONLY_ALLOWED" : "true",
    "ATTESTATION_IOS_APP_ATTEST_MODE" : "OFF",
    "ATTESTATION_ANDROID_SAFETYNET_MODE" : "OFF",
    "APN_EXPIRY" : "86400000",
    "APNS_TIME_SENSITIVE_INTERRUPTION_LEVEL_ENABLED" : "false",
    "GEOFENCING_AUTHENTICATION_MODE" : "OFF",
    "APN_CONFIG" : "PRODUCTION",
    "CLIENT_REQUEST_TIME_VALIDATION_ENABLED" : "true",
    "ACTIVATION_CODE_TYPE" : "NUMERIC",
    "AMOUNT_FAILURES_ALLOWED" : "3",
    "ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY" : "1000",
    "ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE" : "OFF",
    "APNS_NOTIFICATION_SOUND_ENABLED" : "false",
    "GEOFENCING_TIMEOUT" : "10000",
    "PIN_CODE_LENGTH" : "4",
    "ACTIVATION_CODE_LENGTH" : "6",
    "PIN_CODE_TYPE" : "NUMERIC",
    "NATIVE_PUSH_ENABLED" : "true",
    "RECOVERY_CODE_AMOUNT_FAILURES_ALLOWED" : "3",
    "FIREBASE_TIME_TO_LIVE" : "0",
    "ALLOWED_AUTH_METHODS_FOR_AUTH_AND_ACTIVATE" : "DEVICE:PIN",
    "ENABLED_RISK_DATA" : "ALL"
  }
}'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 36435db5-5025-4e9d-ba62-4b092af7f0ac
Content-Type: application/json
Content-Length: 1791

{
  "app_id" : "some-new-app",
  "uuid" : "e63bfc30-ab62-4375-9ec1-6f6583a25467",
  "apns_uuid" : "cefdaccc-efc0-41a3-80a8-5de6faf2c053",
  "configuration" : {
    "CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD" : "300000",
    "RECOVERY_CODE_MIN_LENGTH" : "6",
    "GEOFENCING_ACTIVATION_MODE" : "OFF",
    "ATTESTATION_IOS_APP_ATTEST_TIMEOUT" : "20000",
    "ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT" : "PRODUCTION",
    "RECOVERY_CODE_MAX_LENGTH" : "50",
    "ALLOWED_AUTH_METHODS" : "DEVICE, DEVICE:PIN",
    "HWKEY_VALIDATION_STRATEGY" : "SUPPORTED",
    "SESSION_EXPIRY" : "300000",
    "MAXIMUM_SESSION_EXPIRY" : "300000",
    "RECOVERY_ENABLED" : "false",
    "RECOVERY_CODE_FORMAT" : "NUMERIC",
    "MAX_PIN_CODE_LENGTH" : "6",
    "TOKEN_TYPE" : "SAML2",
    "AUTHORIZATION_TOKEN_TIMEOUT" : "300000",
    "URL_SCHEME" : "encap",
    "CLIENT_ONLY_ALLOWED" : "true",
    "ATTESTATION_IOS_APP_ATTEST_MODE" : "OFF",
    "ATTESTATION_ANDROID_SAFETYNET_MODE" : "OFF",
    "APN_EXPIRY" : "86400000",
    "APNS_TIME_SENSITIVE_INTERRUPTION_LEVEL_ENABLED" : "false",
    "GEOFENCING_AUTHENTICATION_MODE" : "OFF",
    "APN_CONFIG" : "PRODUCTION",
    "CLIENT_REQUEST_TIME_VALIDATION_ENABLED" : "true",
    "ACTIVATION_CODE_TYPE" : "NUMERIC",
    "AMOUNT_FAILURES_ALLOWED" : "3",
    "ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY" : "1000",
    "ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE" : "OFF",
    "APNS_NOTIFICATION_SOUND_ENABLED" : "false",
    "GEOFENCING_TIMEOUT" : "10000",
    "PIN_CODE_LENGTH" : "4",
    "ACTIVATION_CODE_LENGTH" : "6",
    "PIN_CODE_TYPE" : "NUMERIC",
    "NATIVE_PUSH_ENABLED" : "true",
    "RECOVERY_CODE_AMOUNT_FAILURES_ALLOWED" : "3",
    "FIREBASE_TIME_TO_LIVE" : "0",
    "ALLOWED_AUTH_METHODS_FOR_AUTH_AND_ACTIVATE" : "DEVICE:PIN",
    "ENABLED_RISK_DATA" : "ALL"
  }
}

4.2.4. Get application configuration

GET /api/admin/v1/appconfig/{uuid}

Returns the application configuration object with the uuid.

Example request
$ curl 'http://localhost:8080/api/admin/v1/appconfig/c548995c-58a0-4d49-870f-805bb335ba92' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET \
    -H 'Content-Type: application/json'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 33be1cd4-49f1-4805-b842-bafdf9fd45ee
Content-Type: application/json
Content-Length: 1793

{
  "app_id" : "encapApiTest",
  "uuid" : "c548995c-58a0-4d49-870f-805bb335ba92",
  "apns_uuid" : "13f81aca-69dd-4df2-91b7-732261a6b10f",
  "app_name" : "applicationName",
  "configuration" : {
    "ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY" : "1000",
    "ACTIVATION_CODE_LENGTH" : "6",
    "ACTIVATION_CODE_TYPE" : "NUMERIC",
    "ALLOWED_AUTH_METHODS" : "DEVICE, DEVICE:PIN",
    "ALLOWED_AUTH_METHODS_FOR_AUTH_AND_ACTIVATE" : "DEVICE:PIN",
    "AMOUNT_FAILURES_ALLOWED" : "3",
    "APNS_NOTIFICATION_SOUND_ENABLED" : "false",
    "APNS_TIME_SENSITIVE_INTERRUPTION_LEVEL_ENABLED" : "false",
    "APN_CONFIG" : "PRODUCTION",
    "APN_EXPIRY" : "86400000",
    "ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE" : "OFF",
    "ATTESTATION_ANDROID_SAFETYNET_MODE" : "OFF",
    "ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT" : "PRODUCTION",
    "ATTESTATION_IOS_APP_ATTEST_MODE" : "OFF",
    "ATTESTATION_IOS_APP_ATTEST_TIMEOUT" : "20000",
    "AUTHORIZATION_TOKEN_TIMEOUT" : "300000",
    "CLIENT_ONLY_ALLOWED" : "true",
    "CLIENT_REQUEST_TIME_VALIDATION_ENABLED" : "true",
    "CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD" : "300000",
    "FIREBASE_TIME_TO_LIVE" : "0",
    "GEOFENCING_ACTIVATION_MODE" : "OFF",
    "GEOFENCING_AUTHENTICATION_MODE" : "OFF",
    "GEOFENCING_TIMEOUT" : "10000",
    "HWKEY_VALIDATION_STRATEGY" : "SUPPORTED",
    "MAXIMUM_SESSION_EXPIRY" : "300000",
    "MAX_PIN_CODE_LENGTH" : "4",
    "NATIVE_PUSH_ENABLED" : "false",
    "PIN_CODE_LENGTH" : "4",
    "PIN_CODE_TYPE" : "NUMERIC",
    "RECOVERY_CODE_AMOUNT_FAILURES_ALLOWED" : "3",
    "RECOVERY_CODE_FORMAT" : "NUMERIC",
    "RECOVERY_CODE_MAX_LENGTH" : "50",
    "RECOVERY_CODE_MIN_LENGTH" : "6",
    "RECOVERY_ENABLED" : "false",
    "SESSION_EXPIRY" : "300000",
    "TOKEN_TYPE" : "SAML2",
    "URL_SCHEME" : "encap"
  }
}

4.2.5. Get all application configurations

This API was introduced in version 3.9

GET /api/admin/v1/appconfig?limit=10&offset=0

Returns a pagination object with a list of application configuration objects that belongs to your organization.

Example request
$ curl 'http://localhost:8080/api/admin/v1/appconfig?limit=3&offset=1f1e76ff-5356-40e0-861c-29d10a010798' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 22d1afb2-8548-450e-92b2-e829b8f35fe7
Content-Type: application/json
Content-Length: 6001

{
  "previous" : "/admin/v1/appconfig?limit=3&offset=e75eacfd-3958-47cf-b2a8-152e50ac6e91",
  "next" : "/admin/v1/appconfig?limit=3&offset=da1a6026-197b-4b10-8433-1528cdfdf62f",
  "offset" : "1f1e76ff-5356-40e0-861c-29d10a010798",
  "limit" : 3,
  "items" : [ {
    "app_id" : "Application-0",
    "uuid" : "72f9d256-f777-4d69-8c9a-84b20771ade6",
    "apns_uuid" : "1c786dca-87ab-4370-bf80-2d74b294a3bb",
    "app_name" : "Application Name 0",
    "status" : "ENABLED",
    "configuration" : {
      "CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD" : "300000",
      "RECOVERY_CODE_MIN_LENGTH" : "6",
      "GEOFENCING_ACTIVATION_MODE" : "OFF",
      "ATTESTATION_IOS_APP_ATTEST_TIMEOUT" : "20000",
      "ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT" : "PRODUCTION",
      "RECOVERY_CODE_MAX_LENGTH" : "50",
      "ALLOWED_AUTH_METHODS" : "DEVICE, DEVICE:PIN",
      "HWKEY_VALIDATION_STRATEGY" : "SUPPORTED",
      "SESSION_EXPIRY" : "300000",
      "MAXIMUM_SESSION_EXPIRY" : "300000",
      "RECOVERY_ENABLED" : "false",
      "RECOVERY_CODE_FORMAT" : "NUMERIC",
      "MAX_PIN_CODE_LENGTH" : "4",
      "TOKEN_TYPE" : "SAML2",
      "AUTHORIZATION_TOKEN_TIMEOUT" : "300000",
      "URL_SCHEME" : "encap",
      "CLIENT_ONLY_ALLOWED" : "true",
      "ATTESTATION_IOS_APP_ATTEST_MODE" : "OFF",
      "ATTESTATION_ANDROID_SAFETYNET_MODE" : "OFF",
      "APN_EXPIRY" : "86400000",
      "APNS_TIME_SENSITIVE_INTERRUPTION_LEVEL_ENABLED" : "false",
      "GEOFENCING_AUTHENTICATION_MODE" : "OFF",
      "APN_CONFIG" : "PRODUCTION",
      "CLIENT_REQUEST_TIME_VALIDATION_ENABLED" : "true",
      "ACTIVATION_CODE_TYPE" : "NUMERIC",
      "AMOUNT_FAILURES_ALLOWED" : "3",
      "ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY" : "1000",
      "ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE" : "OFF",
      "APNS_NOTIFICATION_SOUND_ENABLED" : "false",
      "GEOFENCING_TIMEOUT" : "10000",
      "PIN_CODE_LENGTH" : "4",
      "ACTIVATION_CODE_LENGTH" : "6",
      "PIN_CODE_TYPE" : "NUMERIC",
      "NATIVE_PUSH_ENABLED" : "false",
      "RECOVERY_CODE_AMOUNT_FAILURES_ALLOWED" : "3",
      "FIREBASE_TIME_TO_LIVE" : "0",
      "ALLOWED_AUTH_METHODS_FOR_AUTH_AND_ACTIVATE" : "DEVICE:PIN"
    }
  }, {
    "app_id" : "Application-1",
    "uuid" : "fa2834cd-991c-4e5c-92a1-c1041a274834",
    "apns_uuid" : "728be794-eac3-420e-a453-cf1245993b77",
    "app_name" : "Application Name 1",
    "status" : "ENABLED",
    "configuration" : {
      "CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD" : "300000",
      "RECOVERY_CODE_MIN_LENGTH" : "6",
      "GEOFENCING_ACTIVATION_MODE" : "OFF",
      "ATTESTATION_IOS_APP_ATTEST_TIMEOUT" : "20000",
      "ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT" : "PRODUCTION",
      "RECOVERY_CODE_MAX_LENGTH" : "50",
      "ALLOWED_AUTH_METHODS" : "DEVICE, DEVICE:PIN",
      "HWKEY_VALIDATION_STRATEGY" : "SUPPORTED",
      "SESSION_EXPIRY" : "300000",
      "MAXIMUM_SESSION_EXPIRY" : "300000",
      "RECOVERY_ENABLED" : "false",
      "RECOVERY_CODE_FORMAT" : "NUMERIC",
      "MAX_PIN_CODE_LENGTH" : "4",
      "TOKEN_TYPE" : "SAML2",
      "AUTHORIZATION_TOKEN_TIMEOUT" : "300000",
      "URL_SCHEME" : "encap",
      "CLIENT_ONLY_ALLOWED" : "true",
      "ATTESTATION_IOS_APP_ATTEST_MODE" : "OFF",
      "ATTESTATION_ANDROID_SAFETYNET_MODE" : "OFF",
      "APN_EXPIRY" : "86400000",
      "APNS_TIME_SENSITIVE_INTERRUPTION_LEVEL_ENABLED" : "false",
      "GEOFENCING_AUTHENTICATION_MODE" : "OFF",
      "APN_CONFIG" : "PRODUCTION",
      "CLIENT_REQUEST_TIME_VALIDATION_ENABLED" : "true",
      "ACTIVATION_CODE_TYPE" : "NUMERIC",
      "AMOUNT_FAILURES_ALLOWED" : "3",
      "ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY" : "1000",
      "ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE" : "OFF",
      "APNS_NOTIFICATION_SOUND_ENABLED" : "false",
      "GEOFENCING_TIMEOUT" : "10000",
      "PIN_CODE_LENGTH" : "4",
      "ACTIVATION_CODE_LENGTH" : "6",
      "PIN_CODE_TYPE" : "NUMERIC",
      "NATIVE_PUSH_ENABLED" : "false",
      "RECOVERY_CODE_AMOUNT_FAILURES_ALLOWED" : "3",
      "FIREBASE_TIME_TO_LIVE" : "0",
      "ALLOWED_AUTH_METHODS_FOR_AUTH_AND_ACTIVATE" : "DEVICE:PIN"
    }
  }, {
    "app_id" : "Application-2",
    "uuid" : "6dfe19e3-f038-49bb-b905-1db8c71aee76",
    "apns_uuid" : "e6dcd4b9-0345-4555-a3a9-36d4fccd35bd",
    "app_name" : "Application Name 2",
    "status" : "ENABLED",
    "configuration" : {
      "CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD" : "300000",
      "RECOVERY_CODE_MIN_LENGTH" : "6",
      "GEOFENCING_ACTIVATION_MODE" : "OFF",
      "ATTESTATION_IOS_APP_ATTEST_TIMEOUT" : "20000",
      "ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT" : "PRODUCTION",
      "RECOVERY_CODE_MAX_LENGTH" : "50",
      "ALLOWED_AUTH_METHODS" : "DEVICE, DEVICE:PIN",
      "HWKEY_VALIDATION_STRATEGY" : "SUPPORTED",
      "SESSION_EXPIRY" : "300000",
      "MAXIMUM_SESSION_EXPIRY" : "300000",
      "RECOVERY_ENABLED" : "false",
      "RECOVERY_CODE_FORMAT" : "NUMERIC",
      "MAX_PIN_CODE_LENGTH" : "4",
      "TOKEN_TYPE" : "SAML2",
      "AUTHORIZATION_TOKEN_TIMEOUT" : "300000",
      "URL_SCHEME" : "encap",
      "CLIENT_ONLY_ALLOWED" : "true",
      "ATTESTATION_IOS_APP_ATTEST_MODE" : "OFF",
      "ATTESTATION_ANDROID_SAFETYNET_MODE" : "OFF",
      "APN_EXPIRY" : "86400000",
      "APNS_TIME_SENSITIVE_INTERRUPTION_LEVEL_ENABLED" : "false",
      "GEOFENCING_AUTHENTICATION_MODE" : "OFF",
      "APN_CONFIG" : "PRODUCTION",
      "CLIENT_REQUEST_TIME_VALIDATION_ENABLED" : "true",
      "ACTIVATION_CODE_TYPE" : "NUMERIC",
      "AMOUNT_FAILURES_ALLOWED" : "3",
      "ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY" : "1000",
      "ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE" : "OFF",
      "APNS_NOTIFICATION_SOUND_ENABLED" : "false",
      "GEOFENCING_TIMEOUT" : "10000",
      "PIN_CODE_LENGTH" : "4",
      "ACTIVATION_CODE_LENGTH" : "6",
      "PIN_CODE_TYPE" : "NUMERIC",
      "NATIVE_PUSH_ENABLED" : "false",
      "RECOVERY_CODE_AMOUNT_FAILURES_ALLOWED" : "3",
      "FIREBASE_TIME_TO_LIVE" : "0",
      "ALLOWED_AUTH_METHODS_FOR_AUTH_AND_ACTIVATE" : "DEVICE:PIN"
    }
  } ]
}

4.2.6. Update application configuration

This API was introduced in version 3.9

PATCH /api/admin/v1/appconfig/{uuid}

This patch API follows the RFC 7396 JSON Merge Patch standard. The request body should only include fields that are to be updated. To remove a field, set the value in the key value pair to null. Absence of a key will cause no changes to that field value.

Arguments
Path Type Required Description

status

String

No

The status of the application configuration. ENABLED, DISABLED.

apns_uuid

UUID

No

The UUID of the APNs push certificate or token used. Required if NATIVE_PUSH_ENABLED is true.

app_name

String

No

The human readable name for the application configuration

configuration

Object

No

The application configuration parameters. Parameters follow the JSON Merge Patch standard. Absent parameters will be unaffected.
Returns

Returns an application configuration object if request is processed successfully. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/admin/v1/appconfig/b63192b4-1dfa-4ac0-a515-aa4d029ea0a7' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X PATCH \
    -H 'Content-Type: application/merge-patch+json' \
    -d '{
  "apns_uuid" : "80c7e366-9ac3-4b5d-a994-77bf332d6c1b",
  "app_name" : "New Application Name",
  "status" : "DISABLED",
  "configuration" : {
    "CLIENT_ONLY_ALLOWED" : "false",
    "ATTESTATION_IOS_APP_ATTEST_TIMEOUT" : null
  }
}'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 87a1b288-a566-4c25-8dfd-bf72ece35efa
Content-Type: application/json
Content-Length: 1772

{
  "app_id" : "some-new-app",
  "uuid" : "b63192b4-1dfa-4ac0-a515-aa4d029ea0a7",
  "apns_uuid" : "80c7e366-9ac3-4b5d-a994-77bf332d6c1b",
  "app_name" : "New Application Name",
  "status" : "DISABLED",
  "configuration" : {
    "CLIENT_REQUEST_TIME_VALIDATION_THRESHOLD" : "300000",
    "RECOVERY_CODE_MIN_LENGTH" : "6",
    "GEOFENCING_ACTIVATION_MODE" : "OFF",
    "ATTESTATION_IOS_APP_ATTEST_ENVIRONMENT" : "PRODUCTION",
    "RECOVERY_CODE_MAX_LENGTH" : "50",
    "ALLOWED_AUTH_METHODS" : "DEVICE, DEVICE:PIN",
    "HWKEY_VALIDATION_STRATEGY" : "SUPPORTED",
    "SESSION_EXPIRY" : "300000",
    "MAXIMUM_SESSION_EXPIRY" : "300000",
    "RECOVERY_ENABLED" : "false",
    "RECOVERY_CODE_FORMAT" : "NUMERIC",
    "MAX_PIN_CODE_LENGTH" : "4",
    "TOKEN_TYPE" : "SAML2",
    "AUTHORIZATION_TOKEN_TIMEOUT" : "300000",
    "URL_SCHEME" : "encap",
    "CLIENT_ONLY_ALLOWED" : "false",
    "ATTESTATION_IOS_APP_ATTEST_MODE" : "OFF",
    "ATTESTATION_ANDROID_SAFETYNET_MODE" : "OFF",
    "APN_EXPIRY" : "86400000",
    "APNS_TIME_SENSITIVE_INTERRUPTION_LEVEL_ENABLED" : "false",
    "GEOFENCING_AUTHENTICATION_MODE" : "OFF",
    "APN_CONFIG" : "PRODUCTION",
    "CLIENT_REQUEST_TIME_VALIDATION_ENABLED" : "true",
    "ACTIVATION_CODE_TYPE" : "NUMERIC",
    "AMOUNT_FAILURES_ALLOWED" : "3",
    "ACTIVATION_CODE_ALLOWED_GUESS_PROBABILITY" : "1000",
    "ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE" : "OFF",
    "APNS_NOTIFICATION_SOUND_ENABLED" : "false",
    "GEOFENCING_TIMEOUT" : "10000",
    "PIN_CODE_LENGTH" : "4",
    "ACTIVATION_CODE_LENGTH" : "6",
    "PIN_CODE_TYPE" : "NUMERIC",
    "NATIVE_PUSH_ENABLED" : "false",
    "RECOVERY_CODE_AMOUNT_FAILURES_ALLOWED" : "3",
    "FIREBASE_TIME_TO_LIVE" : "0",
    "ALLOWED_AUTH_METHODS_FOR_AUTH_AND_ACTIVATE" : "DEVICE:PIN"
  }
}

4.2.7. Delete application configuration

DELETE /api/admin/v1/appconfig/{uuid}

Removes an application configuration with the uuid.

Example request
$ curl 'http://localhost:8080/api/admin/v1/appconfig/51d37a4c-fe05-4a78-998d-c0dc005409f1' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE \
    -H 'Content-Type: application/json'
Example response
HTTP/1.1 202 Accepted
X-Correlation-UUID: cfc75362-2b6f-4db7-bd1d-8f6235a058a8

4.3. APNs Certificate

An API to create and retrieve APNs Certificates. Once a certificate is associated with an application configuration, that application will then use the APNs Certificate to send push notifications to Apple devices. Encap supports APNs tokens from version 3.10, for details on how configure an APNs token please see the Encap Administration Manual. Version: 3.7 or greater

4.3.1. The APNs object

Field Type Description

id

UUID

The UUID for the APNS certificate

name

String

The name of the APNS certificate

sha1_fingerprint

String

The SHA1 hash of the APNS certificate

sha256_fingerprint

String

The SHA256 hash of the APNS certificate

description

String

The description of the APNS certificate

valid_from

String

The start date of the certificate validity period

valid_until

String

The end date of the certificate validity period

subject

String

The subject distinguished name from the certificate

issuer

String

The issuer distinguished name from the certificate

created_by

String

The name/id of the creator of the APNS certificate

created_on

String

The date for when the APNS certificate was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

4.3.2. Create APNs Certificate

POST /api/admin/v1/apns

Creates a new APNs Certificate with the provided values

Arguments
Path Type Required Description

name

String

Yes

The name of the APNS certificate

description

String

No

The description of the APNS certificate

apns_certificate_b64

String

Yes

The Base64 encoded string of the APNS certificate bytes

password

String

Yes

The password associated with the APNS certificate
Returns

Returns an apns certificate object if the request was processed successfully, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/admin/v1/apns' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "test-cert-name",
  "description" : "test-cert-description",
  "apns_certificate_b64" : "somelongb64encodedstring",
  "password" : "test-cert-password"
}'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 622dca44-926a-40b1-90f3-926f06cda455
Content-Type: application/json
Content-Length: 739

{
  "id" : "bec34d37-bb58-4d67-ad8f-3a4c45d812ae",
  "name" : "test-cert-name",
  "description" : "test-cert-description",
  "created_by" : "someuser",
  "created_on" : "2023-09-28T11:29:32.689UTC",
  "sha1_fingerprint" : "fb:14:98:36:7e:b8:b9:78:de:18:2b:1a:30:69:49:94:7b:5f:65:67",
  "sha256_fingerprint" : "12:e0:23:b0:96:c5:b2:40:7a:bf:fb:2f:0d:4c:5c:c0:e3:f0:55:0c:eb:40:55:69:ef:47:de:09:2b:fd:aa:68",
  "valid_from" : "2022-11-29T14:10:10.000UTC",
  "valid_until" : "2023-12-29T14:10:09.000UTC",
  "subject" : "C=NO,O=Signicat AS,OU=Y2Y8VXX8PM,CN=Apple Push Services: com.signicat.encap.TestApp,UID=com.signicat.encap.TestApp",
  "issuer" : "C=US,O=Apple Inc.,OU=G4,CN=Apple Worldwide Developer Relations Certification Authority"
}

4.3.3. Get APNs Certificate details

GET /api/admin/v1/apns/{apnsId}

Get meta data for the APNs Certificate

Returns

Returns a apns certificate object if a valid identifier was provided, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/admin/v1/apns/bec34d37-bb58-4d67-ad8f-3a4c45d812ae' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: c13611e8-5b9e-49e0-b432-980f26fd3bcb
Content-Type: application/json
Content-Length: 739

{
  "id" : "bec34d37-bb58-4d67-ad8f-3a4c45d812ae",
  "name" : "test-cert-name",
  "description" : "test-cert-description",
  "created_by" : "someuser",
  "created_on" : "2023-09-28T11:29:31.347UTC",
  "sha1_fingerprint" : "fb:14:98:36:7e:b8:b9:78:de:18:2b:1a:30:69:49:94:7b:5f:65:67",
  "sha256_fingerprint" : "12:e0:23:b0:96:c5:b2:40:7a:bf:fb:2f:0d:4c:5c:c0:e3:f0:55:0c:eb:40:55:69:ef:47:de:09:2b:fd:aa:68",
  "valid_from" : "2022-11-29T14:10:10.000UTC",
  "valid_until" : "2023-12-29T14:10:09.000UTC",
  "subject" : "C=NO,O=Signicat AS,OU=Y2Y8VXX8PM,CN=Apple Push Services: com.signicat.encap.TestApp,UID=com.signicat.encap.TestApp",
  "issuer" : "C=US,O=Apple Inc.,OU=G4,CN=Apple Worldwide Developer Relations Certification Authority"
}

4.3.4. Get all APNs Certificates

This API was introduced in version 3.9

GET /api/admin/v1/apns

Returns a pagination object with a list of apns certificate objects that belongs to your organization.

Example request
$ curl 'http://localhost:8080/api/admin/v1/apns?limit=3&offset=704973d6-efa7-40a8-8200-5fd1b6b48c9f' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 860f86e7-34b5-403b-ab28-b8eefa714c70
Content-Type: application/json
Content-Length: 2547

{
  "previous" : "/admin/v1/apns?limit=3&offset=58404e29-9701-4e03-8d94-a8e5c73fc479",
  "next" : "/admin/v1/apns?limit=3&offset=83ec8a18-58c5-4798-8512-7708551b2f44",
  "offset" : "704973d6-efa7-40a8-8200-5fd1b6b48c9f",
  "limit" : 3,
  "items" : [ {
    "id" : "02778ceb-dc7b-43f3-b651-3b26d6f1161f",
    "name" : "test-cert-name",
    "description" : "test-cert-description",
    "created_by" : "someuser",
    "created_on" : "2023-09-28T11:29:32.444UTC",
    "sha1_fingerprint" : "fb:14:98:36:7e:b8:b9:78:de:18:2b:1a:30:69:49:94:7b:5f:65:67",
    "sha256_fingerprint" : "12:e0:23:b0:96:c5:b2:40:7a:bf:fb:2f:0d:4c:5c:c0:e3:f0:55:0c:eb:40:55:69:ef:47:de:09:2b:fd:aa:68",
    "valid_from" : "2022-11-29T14:10:10.000UTC",
    "valid_until" : "2023-12-29T14:10:09.000UTC",
    "subject" : "C=NO,O=Signicat AS,OU=Y2Y8VXX8PM,CN=Apple Push Services: com.signicat.encap.TestApp,UID=com.signicat.encap.TestApp",
    "issuer" : "C=US,O=Apple Inc.,OU=G4,CN=Apple Worldwide Developer Relations Certification Authority"
  }, {
    "id" : "5403f3fe-0b08-413b-b6a8-b537401e30bc",
    "name" : "test-cert-name",
    "description" : "test-cert-description",
    "created_by" : "someuser",
    "created_on" : "2023-09-28T11:29:32.499UTC",
    "sha1_fingerprint" : "fb:14:98:36:7e:b8:b9:78:de:18:2b:1a:30:69:49:94:7b:5f:65:67",
    "sha256_fingerprint" : "12:e0:23:b0:96:c5:b2:40:7a:bf:fb:2f:0d:4c:5c:c0:e3:f0:55:0c:eb:40:55:69:ef:47:de:09:2b:fd:aa:68",
    "valid_from" : "2022-11-29T14:10:10.000UTC",
    "valid_until" : "2023-12-29T14:10:09.000UTC",
    "subject" : "C=NO,O=Signicat AS,OU=Y2Y8VXX8PM,CN=Apple Push Services: com.signicat.encap.TestApp,UID=com.signicat.encap.TestApp",
    "issuer" : "C=US,O=Apple Inc.,OU=G4,CN=Apple Worldwide Developer Relations Certification Authority"
  }, {
    "id" : "d6e7e47d-5a9a-429e-8169-c02a6a639f35",
    "name" : "test-cert-name",
    "description" : "test-cert-description",
    "created_by" : "someuser",
    "created_on" : "2023-09-28T11:29:32.554UTC",
    "sha1_fingerprint" : "fb:14:98:36:7e:b8:b9:78:de:18:2b:1a:30:69:49:94:7b:5f:65:67",
    "sha256_fingerprint" : "12:e0:23:b0:96:c5:b2:40:7a:bf:fb:2f:0d:4c:5c:c0:e3:f0:55:0c:eb:40:55:69:ef:47:de:09:2b:fd:aa:68",
    "valid_from" : "2022-11-29T14:10:10.000UTC",
    "valid_until" : "2023-12-29T14:10:09.000UTC",
    "subject" : "C=NO,O=Signicat AS,OU=Y2Y8VXX8PM,CN=Apple Push Services: com.signicat.encap.TestApp,UID=com.signicat.encap.TestApp",
    "issuer" : "C=US,O=Apple Inc.,OU=G4,CN=Apple Worldwide Developer Relations Certification Authority"
  } ]
}

4.3.5. Delete APNs Certificate

DELETE /api/admin/v1/apns/{apnsId}

Deletes the APNs certificate with the apnsId

Example request
$ curl 'http://localhost:8080/api/admin/v1/apns/84549fdd-00a0-48fe-84ed-66a5476eedbf' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: af7a7cba-4aa3-4e3d-b303-4eaec3724186

4.4. APNs Provider Token

An API to add and retrieve APNs provider tokens. Version: 3.12 or greater

4.4.1. The APNs provider token object

Field Type Description

id

UUID

The UUID for the APNs token

name

String

The name of the APNs token

sha1_fingerprint

String

The SHA1 hash of the APNs token

sha256_fingerprint

String

The SHA256 hash of the APNs token

description

String

The description of the APNs token

key_id

String

Key ID of the APNs token

team_id

String

Team ID of Apple Developer Account

created_by

String

The name/id of the creator of the APNs token

created_on

String

The date for when the APNs token was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

4.4.2. Add APNs provider token

POST /api/admin/v1/apnstokens

Adds a new APNs provider token with the provided values (from the Apple Developer Portal).

Arguments
Path Type Required Description

name

String

Yes

The name of the APNs token

description

String

No

The description of the APNs token

private_key_b64

String

Yes

The Base64 encoded string of APNs token private key

key_id

String

Yes

Key ID of the APNs token

team_id

String

Yes

Team ID of Apple Developer Account
Returns

Returns an APNs provider token object if the request was processed successfully, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/admin/v1/apnstokens' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "test-token-name",
  "description" : "test-token-description",
  "private_key_b64" : "privateKeyString",
  "key_id" : "key-id",
  "team_id" : "team-id"
}'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 9136790a-5013-4956-9585-53ccf0928de6
Content-Type: application/json
Content-Length: 467

{
  "id" : "393653b2-7195-4a37-b062-9a73ee39de78",
  "name" : "test-cert-name",
  "description" : "test-cert-description",
  "created_by" : "someuser",
  "created_on" : "2023-09-28T11:29:33.278UTC",
  "sha1_fingerprint" : "aa:6b:bb:f2:e3:5e:8f:91:5b:db:11:0a:27:45:0d:59:61:73:3d:6e",
  "sha256_fingerprint" : "29:31:57:72:39:ec:78:84:ad:30:68:1a:e3:dc:5a:19:a5:4b:0c:f5:05:c7:48:56:14:59:28:a0:67:97:18:99",
  "key_id" : "test-key-id",
  "team_id" : "test-team-id"
}

4.4.3. Get APNs provider token details

GET /api/admin/v1/apnstokens/{apnsTokenId}

Get metadata for an APNs provider token

Returns

Returns a APNs provider token object if a valid identifier was provided, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/admin/v1/apnstokens/393653b2-7195-4a37-b062-9a73ee39de78' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 51205c03-27f8-4fef-b64f-e1f97581bce9
Content-Type: application/json
Content-Length: 467

{
  "id" : "393653b2-7195-4a37-b062-9a73ee39de78",
  "name" : "test-cert-name",
  "description" : "test-cert-description",
  "created_by" : "someuser",
  "created_on" : "2023-09-28T11:29:33.050UTC",
  "sha1_fingerprint" : "aa:6b:bb:f2:e3:5e:8f:91:5b:db:11:0a:27:45:0d:59:61:73:3d:6e",
  "sha256_fingerprint" : "29:31:57:72:39:ec:78:84:ad:30:68:1a:e3:dc:5a:19:a5:4b:0c:f5:05:c7:48:56:14:59:28:a0:67:97:18:99",
  "key_id" : "test-key-id",
  "team_id" : "test-team-id"
}

4.4.4. Get all APNs provider tokens

GET /api/admin/v1/apnstokens

Returns a pagination object with a list of APNs provider token objects that belongs to your organization.

Example request
$ curl 'http://localhost:8080/api/admin/v1/apnstokens?limit=3&offset=b277bd41-8026-48c7-99d7-e1858449ac50' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 212de782-a724-4cc8-82fc-ff99bffa60bc
Content-Type: application/json
Content-Length: 1731

{
  "previous" : "/admin/v1/apnstokens?limit=3&offset=d1578f10-d78a-496d-90bb-8cad2bb544c0",
  "next" : "/admin/v1/apnstokens?limit=3&offset=5ebde25a-018a-4bf8-ad10-7fc1aa82e10c",
  "offset" : "b277bd41-8026-48c7-99d7-e1858449ac50",
  "limit" : 3,
  "items" : [ {
    "id" : "35312a6d-47c6-40db-ab31-bc960a59ec6d",
    "name" : "test-cert-name",
    "description" : "test-cert-description",
    "created_by" : "someuser",
    "created_on" : "2023-09-28T11:29:33.351UTC",
    "sha1_fingerprint" : "aa:6b:bb:f2:e3:5e:8f:91:5b:db:11:0a:27:45:0d:59:61:73:3d:6e",
    "sha256_fingerprint" : "29:31:57:72:39:ec:78:84:ad:30:68:1a:e3:dc:5a:19:a5:4b:0c:f5:05:c7:48:56:14:59:28:a0:67:97:18:99",
    "key_id" : "test-key-id",
    "team_id" : "test-team-id"
  }, {
    "id" : "4c5402f0-0986-4ce1-82a2-e8b23903b085",
    "name" : "test-cert-name",
    "description" : "test-cert-description",
    "created_by" : "someuser",
    "created_on" : "2023-09-28T11:29:33.351UTC",
    "sha1_fingerprint" : "aa:6b:bb:f2:e3:5e:8f:91:5b:db:11:0a:27:45:0d:59:61:73:3d:6e",
    "sha256_fingerprint" : "29:31:57:72:39:ec:78:84:ad:30:68:1a:e3:dc:5a:19:a5:4b:0c:f5:05:c7:48:56:14:59:28:a0:67:97:18:99",
    "key_id" : "test-key-id",
    "team_id" : "test-team-id"
  }, {
    "id" : "8b8a2212-553d-40ba-9926-1f20a0193d43",
    "name" : "test-cert-name",
    "description" : "test-cert-description",
    "created_by" : "someuser",
    "created_on" : "2023-09-28T11:29:33.351UTC",
    "sha1_fingerprint" : "aa:6b:bb:f2:e3:5e:8f:91:5b:db:11:0a:27:45:0d:59:61:73:3d:6e",
    "sha256_fingerprint" : "29:31:57:72:39:ec:78:84:ad:30:68:1a:e3:dc:5a:19:a5:4b:0c:f5:05:c7:48:56:14:59:28:a0:67:97:18:99",
    "key_id" : "test-key-id",
    "team_id" : "test-team-id"
  } ]
}

4.4.5. Delete APNs provider token

DELETE /api/admin/v1/apnstokens/{apnsTokenId}

Deletes the APNs provider token with the apnsTokenId

Example request
$ curl 'http://localhost:8080/api/admin/v1/apnstokens/1e5d1e1a-2472-4473-9c48-783f7d04005b' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: 1613cad9-7ef9-457e-97e4-02e063fa1624

4.5. API Key

An API to manage API keys. API keys are used to authenticate on all Encap REST APIs. Introduced in Encap 3.13

4.5.1. The API key object

Field Type Description

api_key_id

UUID

The API key ID, UUID, for the key.

api_key_secret

String

The API key secret. The secret is only part of the response when a API key is created, it is not returned when you fetch an API key

description

String

The description for the API key

created_by

String

The name/id of the creator of the API key

created_on

String

The date for when the API key was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

4.5.2. Create API Key

POST /api/admin/v1/api-keys

Create a new API key

Arguments
Path Type Required Description

description

String

No

The description for the API key
Returns

Returns an API key object if the request was processed successfully, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/admin/v1/api-keys' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "description" : "Key for client A"
}'
Example response
HTTP/1.1 201 Created
X-Correlation-UUID: a8c33726-825a-4333-a2ff-352c70e7d0c6
Location: /admin/v1/api-keys/14de9210-8e30-408e-9a38-411bb75a2d5b
Content-Type: application/json
Content-Length: 250

{
  "api_key_id" : "14de9210-8e30-408e-9a38-411bb75a2d5b",
  "created_on" : "2023-09-28T11:29:30.555UTC",
  "created_by" : "07a95e57-86a5-42df-b221-67f7dc131eca",
  "description" : "Key for client A",
  "api_key_secret" : "38ZpcEB0bKdC+bFJr5mXuQ=="
}

4.5.3. Get API key details

GET /api/admin/v1/api-keys/{api_key_id}

Get details for an API key.

Returns

Returns a API key object if a valid identifier was provided, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/admin/v1/api-keys/14de9210-8e30-408e-9a38-411bb75a2d5b' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: e8d820ae-18f9-4d16-a79c-cc61b7f129a6
Content-Type: application/json
Content-Length: 201

{
  "api_key_id" : "14de9210-8e30-408e-9a38-411bb75a2d5b",
  "created_on" : "2023-09-28T11:29:30.454UTC",
  "created_by" : "07a95e57-86a5-42df-b221-67f7dc131eca",
  "description" : "Key for client A"
}

4.5.4. Get all API keys

GET /api/admin/v1/api-keys

Returns a pagination object with a list of API key objects that belongs your organization.

Example request
$ curl 'http://localhost:8080/api/admin/v1/api-keys/?limit=3&offset=dfbb2292-b91d-4ba1-a25d-39da5c524f58' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 55c2056f-7adb-46ff-89c2-05c26267211b
Content-Type: application/json
Content-Length: 899

{
  "previous" : "/admin/v1/api-keys?limit=3&offset=b2fce6dd-1af1-44ad-9d7b-1cc17af58797",
  "next" : "/admin/v1/api-keys?limit=3&offset=4012d559-8e69-4f67-99fb-ab32bdddd833",
  "offset" : "dfbb2292-b91d-4ba1-a25d-39da5c524f58",
  "limit" : 3,
  "items" : [ {
    "api_key_id" : "e83d55b4-af76-4460-af6b-efbe829dfc4b",
    "created_on" : "2023-09-28T11:29:30.340UTC",
    "created_by" : "07a95e57-86a5-42df-b221-67f7dc131eca",
    "description" : "Key for client A"
  }, {
    "api_key_id" : "c1ed6b29-2b56-42b5-ab8d-6f9537d398b6",
    "created_on" : "2023-09-28T11:29:30.340UTC",
    "created_by" : "07a95e57-86a5-42df-b221-67f7dc131eca",
    "description" : "Key for client A"
  }, {
    "api_key_id" : "b245cebf-4b89-4d25-ae97-1e0102a42948",
    "created_on" : "2023-09-28T11:29:30.340UTC",
    "created_by" : "07a95e57-86a5-42df-b221-67f7dc131eca",
    "description" : "Key for client A"
  } ]
}

4.5.5. Delete API key

DELETE /api/admin/v1/api-keys/{api_key_id}

Deletes the API key with the specified id

Example request
$ curl 'http://localhost:8080/api/admin/v1/api-keys/14de9210-8e30-408e-9a38-411bb75a2d5b' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: 453461bd-a844-4220-a81e-953f122dfd18

4.6. End-to-End Key

End-to-End keys are used by Encap to create an additional encryption layer between the Encap Server and the SDK. This API is used to create and manage the End-to-End encryption keys used in this layer. Each organisation needs at least one End-to-End Key, but preferably you should have one key per application.

4.6.1. The End-to-End Key Object

Field Type Description

id

UUID

The UUID for the End-To-End key

name

String

Name for the End-To-End key

description

String

Description for the End-To-End key

created_by

String

The name/id of the creator of the End-To-End key

created_on

String

The date for when the End-To-End key was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

sha256_fingerprint

String

The SHA256 hash of the End-To-End key certificate

public_key

String

Base64 encoded End-To-End key certificate

organization_id

UUID

The UUID for the organization that owns this End-To-End key

status

String

Status of the End-To-End key. Possible values are ENABLED and DISABLED

4.6.2. Create End-to-End Key

POST /api/admin/v1/e2e-keys

Create a new End-to-End Key. A new End-to-End key pair is generated by the server and the public key is sent back in the response.

Arguments
Path Type Required Description

name

String

Yes

The name of the End-To-End key

description

String

No

Description for the End-To-End key
Returns

Returns an End-to-End Key object if the request was processed successfully, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/admin/v1/e2e-keys' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "name" : "test-e2e-key-name",
  "description" : "test-e2e-key-description"
}'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 906be2a0-a37a-4ef8-a962-458ffb95190e
Content-Type: application/json
Content-Length: 551

{
  "id" : "9999e032-94cf-4ea4-96ac-ab665018d10a",
  "name" : "test-e2e-cert-name",
  "description" : "test-e2e-cert-description",
  "created_by" : "someuser",
  "created_on" : "2022-11-30T18:35:24.000UTC",
  "sha256_fingerprint" : "71:04:a9:dc:e4:3c:23:fe:d8:d3:8f:79:f0:d7:1a:2e:35:7d:c6:de:6d:fd:19:9e:07:74:23:35:82:83:37:22",
  "public_key" : "MFIwEAYHKoZIzj0CAQYFK4EEABoDPgAEAfdEY0BYY8yINZaHED77apY3/nZK3HZSnkUOrqUVAUcHe+RGt/iitJy8CGQmMjPA/gql5mREyiAPAPg2",
  "organization_id" : "227cb314-9f0d-47cb-afa8-9999be9e2010",
  "status" : "DISABLED"
}

4.6.3. Get End-to-End Key details

GET /api/admin/v1/e2e-keys/{e2eKeyId}

Get details for an End-to-End Key.

Returns

Returns a End-to-End Key object if a valid identifier was provided, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/admin/v1/e2e-keys/9999e032-94cf-4ea4-96ac-ab665018d10a' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 099a14c2-ee4b-4bcf-ab6d-28a1eed0828a
Content-Type: application/json
Content-Length: 551

{
  "id" : "9999e032-94cf-4ea4-96ac-ab665018d10a",
  "name" : "test-e2e-cert-name",
  "description" : "test-e2e-cert-description",
  "created_by" : "someuser",
  "created_on" : "2022-11-30T18:35:24.000UTC",
  "sha256_fingerprint" : "71:04:a9:dc:e4:3c:23:fe:d8:d3:8f:79:f0:d7:1a:2e:35:7d:c6:de:6d:fd:19:9e:07:74:23:35:82:83:37:22",
  "public_key" : "MFIwEAYHKoZIzj0CAQYFK4EEABoDPgAEAfdEY0BYY8yINZaHED77apY3/nZK3HZSnkUOrqUVAUcHe+RGt/iitJy8CGQmMjPA/gql5mREyiAPAPg2",
  "organization_id" : "e3ac910a-f2bb-413f-b087-9bdd2342e741",
  "status" : "DISABLED"
}

4.6.4. Get all End-to-End Keys

GET /api/admin/v1/e2e-keys

Returns a pagination object with a list of End-to-End Key objects that belongs your organization.

Example request
$ curl 'http://localhost:8080/api/admin/v1/e2e-keys?limit=3&offset=600e9b4c-f6d3-499f-be00-53dfa595ef13' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: f4d0c22f-c8c6-47e9-8923-34af9d21b9dc
Content-Type: application/json
Content-Length: 1979

{
  "previous" : "/admin/v1/e2e-keys?limit=3&offset=ade0c09f-5bc2-4896-a03c-27e7e4570f49",
  "next" : "/admin/v1/e2e-keys?limit=3&offset=9220992f-555b-428c-a676-7e028cf9da6d",
  "offset" : "600e9b4c-f6d3-499f-be00-53dfa595ef13",
  "limit" : 3,
  "items" : [ {
    "id" : "d1802b2f-6f76-4345-b93b-b70e1533afaf",
    "name" : "test-e2e-cert-name",
    "description" : "test-e2e-cert-description",
    "created_by" : "someuser",
    "created_on" : "2022-11-30T18:35:24.000UTC",
    "sha256_fingerprint" : "71:04:a9:dc:e4:3c:23:fe:d8:d3:8f:79:f0:d7:1a:2e:35:7d:c6:de:6d:fd:19:9e:07:74:23:35:82:83:37:22",
    "public_key" : "MFIwEAYHKoZIzj0CAQYFK4EEABoDPgAEAfdEY0BYY8yINZaHED77apY3/nZK3HZSnkUOrqUVAUcHe+RGt/iitJy8CGQmMjPA/gql5mREyiAPAPg2",
    "organization_id" : "d9608dc8-bedc-4490-ad6d-30a98aa05e00",
    "status" : "DISABLED"
  }, {
    "id" : "04a81226-ee7d-4d16-ae3f-e8f1ee456bb9",
    "name" : "test-e2e-cert-name",
    "description" : "test-e2e-cert-description",
    "created_by" : "someuser",
    "created_on" : "2022-11-30T18:35:24.000UTC",
    "sha256_fingerprint" : "71:04:a9:dc:e4:3c:23:fe:d8:d3:8f:79:f0:d7:1a:2e:35:7d:c6:de:6d:fd:19:9e:07:74:23:35:82:83:37:22",
    "public_key" : "MFIwEAYHKoZIzj0CAQYFK4EEABoDPgAEAfdEY0BYY8yINZaHED77apY3/nZK3HZSnkUOrqUVAUcHe+RGt/iitJy8CGQmMjPA/gql5mREyiAPAPg2",
    "organization_id" : "e1cbe0d5-e28b-4c90-8941-bede7be9cdcd",
    "status" : "DISABLED"
  }, {
    "id" : "10f0bdde-6f63-43d0-accb-6646ace09192",
    "name" : "test-e2e-cert-name",
    "description" : "test-e2e-cert-description",
    "created_by" : "someuser",
    "created_on" : "2022-11-30T18:35:24.000UTC",
    "sha256_fingerprint" : "71:04:a9:dc:e4:3c:23:fe:d8:d3:8f:79:f0:d7:1a:2e:35:7d:c6:de:6d:fd:19:9e:07:74:23:35:82:83:37:22",
    "public_key" : "MFIwEAYHKoZIzj0CAQYFK4EEABoDPgAEAfdEY0BYY8yINZaHED77apY3/nZK3HZSnkUOrqUVAUcHe+RGt/iitJy8CGQmMjPA/gql5mREyiAPAPg2",
    "organization_id" : "fd8f7d81-a07a-4550-81c8-14cd0b029b1f",
    "status" : "DISABLED"
  } ]
}

4.6.5. Update status of End-to-End Key

PUT /api/admin/v1/e2e-keys/{e2eKeyId}/status

Changing the status of the key. Changing status to DISABLED means that it will no longer be usable for client requests.

Arguments
Path Type Required Description

status

String

Yes

Status to set for the End-To-End key. Possible values are ENABLED and DISABLED
Example request
$ curl 'http://localhost:8080/api/admin/v1/e2e-keys/9999e032-94cf-4ea4-96ac-ab665018d10a/status' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X PUT \
    -H 'Content-Type: application/json' \
    -d '{
  "status" : "DISABLED"
}'
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: e8130c5e-4328-4250-8a4d-5ae6487ccf09
Content-Type: application/json
Content-Length: 27

{
  "status" : "DISABLED"
}

4.6.6. Delete End-to-End Key

DELETE /api/admin/v1/e2e-keys/{e2eKeyId}

Deletes the End-to-End Key with the specified id. You can only delete unused keys (having status set to DISABLED).

Example request
$ curl 'http://localhost:8080/api/admin/v1/e2e-keys/9999e032-94cf-4ea4-96ac-ab665018d10a' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X DELETE
Example response
HTTP/1.1 204 No Content
X-Correlation-UUID: 606540e4-44cf-4601-9422-9fdceffe0189

5. Statistics API

5.1. Encap client versions

An API for extracting statistics about the Encap client version for the devices registered in Encap. The statistics result will provide information on the amount of registrations that has been active within a given time interval, grouped by the Encap version of the client.

5.1.1. Usage

The version statistics extraction is a two-step progress because the actual data-extraction might take some time given a large dataset.

The first call, a POST request, will creates a new asynchrounous job for extracting the version statistics, the request returns an UUID for the version statistics result. This UUID is used in the second step. The second call, a GET request, gets the result of version statistics. If you perform a GET request before the extraction job has finished, the response will have the status IN_PROGRESS.

We also provided a cache functionality for the statistic extraction. If you make a new POST request for the same application configuration and the same time interval as a previous request, that has finished within the cache time period, then the server will not create a new job for extracting the same data. But instead return with the status READY and the UUID of the previous version statistics as a reference. To get the complete response perform a GET request for that UUID. If the previous version extraction has not yet finished, then the server will not start a new extraction job regardless of the cache time, but instead return with the status IN_PROGRESS and the UUID of the previous version statistics as a reference. To get the complete response perform a GET request for that UUID.

The cache time has a default value of one hour. You can change the cache time by providing the cluster-property admin.statistics.cachetime. This value is an integer of seconds.

5.1.2. The encap client versions object

Field Type Description

uuid

UUID

The id of the statistics record

status

String

Status of the statistics record. May be IN_PROGRESS, READY or FAILED

app_config_uuid

UUID

UUID of the app config the statistics are generated for

last_used

Number

Registrations used after the number of days from this field will be included in the statistic

generated_on

String

The time the record was first created

version_statistics

Array

Number of devices used in the last amount of days, dictated by last_used, this is split by version
Field Type Description

encap_client_version

String

Encap client version

count

Number

Number of devices on this version

5.1.3. Request statistics

POST /api/statistics/v1/encap-client-versions
Arguments
Path Type Required Description

app_config_uuid

UUID

Yes

UUID of the app config the statistics are generated for

last_used

Number

Yes

Registrations used after the number of days from this field will be included in the statistic
Example request body
{
  "app_config_uuid" : "327eaba5-f71e-434e-b2c5-e3ea684ae68b",
  "last_used" : 365
}
Returns

Returns an encap client versions object if the request statistics is successfully initiated. Returns an error object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/statistics/v1/encap-client-versions/' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "app_config_uuid" : "327eaba5-f71e-434e-b2c5-e3ea684ae68b",
  "last_used" : 365
}'
Example response:
HTTP/1.1 202 Accepted
X-Correlation-UUID: ed37c083-a2fa-4d9e-adfe-473b52f829ef
Content-Type: application/json
Content-Length: 213

{
  "uuid" : "f68581f8-d8e6-41cc-8fc7-c797145bc715",
  "status" : "IN_PROGRESS",
  "app_config_uuid" : "327eaba5-f71e-434e-b2c5-e3ea684ae68b",
  "last_used" : 365,
  "generated_on" : "2023-09-28T11:29:37.910UTC"
}

5.1.4. Get statistics record

GET /api/statistics/v1/encap-client-versions/{uuid}
Returns

Returns an encap client versions object if a valid identifier was provided, and returns an error otherwise.

Example request
$ curl 'http://localhost:8080/api/statistics/v1/encap-client-versions/f68581f8-d8e6-41cc-8fc7-c797145bc715' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response
HTTP/1.1 200 OK
X-Correlation-UUID: 0dd5ba79-8b90-4a6e-9c6e-01808e45a37d
Content-Type: application/json
Content-Length: 298

{
  "uuid" : "f68581f8-d8e6-41cc-8fc7-c797145bc715",
  "status" : "READY",
  "app_config_uuid" : "327eaba5-f71e-434e-b2c5-e3ea684ae68b",
  "last_used" : 365,
  "generated_on" : "2023-09-28T11:29:37.959UTC",
  "version_statistics" : [ {
    "encap_client_version" : "3.9.0",
    "count" : 10
  } ]
}

6. Callback

Encap supports two different service provider callbacks models, Requested callback and Event callback. Requested callback is requested for each activation or authentication operation, and provides a full response for the operation. Event callbacks are configured on the application configuration, and supports events for activation, authentication in addition to other events. The callback gives a status of the operation and a reference to the full response. Event callback is more resilient against event delivery issues and has a persistent event storage. It is possible to use both Event callback and Requested callback in parallel.

6.1. Requested callback

Callback for device activation and authentication, is used to inform the service provider about the status of a completed activation or authentication. The service provider can then wait for the callback instead of polling the server for status for the ongoing session.

6.1.1. Implementation

The callback endpoint must be implemented by the Service Provider and be reachable from the Encap server.

The endpoint needs to accept POST of the payloads described enrollment callback and here authentication callback.

The Encap server interprets any 2xx response as a success. Any other response will lead to a warning being logged in the server log, but this will have no effect on the status of the ongoing operation.

6.1.2. Usage

If the ´callback_address´ argument is set when creating the authentication object or enrollment, a callback will be sent by the Encap server to this address when the operation is completed (status is SUCCESS or FAILURE).

6.1.3. Important operational behaviour

The callback is performed asynchronously, so the client device will get an immediate response regardless of the availability of the service provider callback endpoint.

In order to monitor the health of the callback service, the operator needs to monitor (and act upon) Encap log messages with WARNING level for failing callbacks. Failure to do so will cause the device to think it is successfully activated or authenticated without the service provider being informed by of the result of the operation.

6.2. Event callback

Event callback reduces the need to poll for status changes. Event callback notifications are sent asynchronously to the service provider for selected events in Encap SCA. Events can also be filtered based on which API that initiated the operation.

6.2.1. Configuration

Event callback global properties

The encap-cluster.properties file contains parameters relevant for the configuration of the Event Callback feature. Cluster wide parameters for polling intervals, retries and timeouts can be configured to control the behaviour of the Event Callback service.

More details about the cluster configuration properties han be found in the Encap Server Administration Manual, chapter "Server config params".

Application configuration parameters

The application configuration parameter EVENT_CALLBACK_EVENTS is used to configure which events and APIs you want to trigger a callback. The EVENT_CALLBACK_URL parameter controls the URL for posting the event-callback objects.

This means that you can have a different set of events/APIs & URL per application config.

More details about the application configuration parameters.

Event types
Event type Description

DEVICE_LOCKED

Device locked (status SUCCESS)

DEVICE_UNLOCKED

Device unlocked (status SUCCESS)

DEVICE_DEACTIVATED

Device deactivated (status SUCCESS)

DEVICE_ACTIVATION

Device activation session completed (status SUCCESS or FAILURE)

DEVICE_AUTHENTICATION

Device authentication session completed (status SUCCESS or FAILURE)
Event APIs
API type Description

DEVICE

Event for operations initiated by the mobile device

REST

Event for operations initiated from the REST API

6.2.2. Event callback service provider API

Event callback API for notifying the service provider when events occur in Encap.

Encap server performs event-callback to service provider
POST /service-provider/event-callback-url

A http POST will be performed when the application configuration for the device has event callback configured

The event callback object
Path Type Required Description

event_id

UUID

Yes

Unique event ID. Can be used to identify duplicate callbacks for the same event (rare state)

subscribed_type

UUID

Yes

The type of event that has occurred. See event-callback-events for possible values

app_config_id

UUID

Yes

The UUID of the owning app-config for this device

device_id

UUID

Yes

The UUID of the device that is affected by or has caused the event

session_id

UUID

No

The UUID of the session that this event belongs to (if any)

status

String

No

Status of the current event (SUCCESS or FAILURE)

ref

String

No

Refers to details about the resource event (if available)
Example request body
{
  "event_id" : "be77a330-1415-4fd2-9f88-a99b66b51b6e",
  "subscribed_type" : "DEVICE_LOCKED",
  "app_config_id" : "043ab771-e41e-471e-b4b9-194aa4cdd013",
  "device_id" : "d69cf120-ef07-4e88-b0cd-2cb73f0b9df4",
  "session_id" : "d2e4afea-4afa-45ff-a5b0-5194de4b84f9",
  "ref" : "/devices/d69cf120-ef07-4e88-b0cd-2cb73f0b9df4/lock",
  "status" : "SUCCESS"
}
Expected response from service provider

Return an empty response, with successful http code if the operation succeeds. Return a non 2xx http code object if something goes wrong.

Example request
$ curl 'http://localhost:8080/api/dummyspeventcallbackcontroller' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "event_id" : "be77a330-1415-4fd2-9f88-a99b66b51b6e",
  "subscribed_type" : "DEVICE_LOCKED",
  "app_config_id" : "043ab771-e41e-471e-b4b9-194aa4cdd013",
  "device_id" : "d69cf120-ef07-4e88-b0cd-2cb73f0b9df4",
  "session_id" : "d2e4afea-4afa-45ff-a5b0-5194de4b84f9",
  "ref" : "/devices/d69cf120-ef07-4e88-b0cd-2cb73f0b9df4/lock",
  "status" : "SUCCESS"
}'
Example response
HTTP/1.1 204 No Content

6.2.3. Event callback status API

This provides a status overview of the event callback queues, including an availability-check of the event callback endpoint provided by the service provider. This will list the queue size for each app-config and perform an HTTP HEAD request towards the event callback endpoints configured.

Response objects types
Overall status object
Field Type Description

status_all

String

Overall queue health status

queues

Array

List of event callback queues
Queue details status object
Field Type Description

id

String

App-config id for the event callback queue

size

Number

Number of items in events callback queue

status

String

Health status of the queue

error

String

If 'status' is FAILURE, the error field should contain details about the failure
Event-callback queue status
Status Description

OK

Queue health status is OK

FAILURE

Queue status is unhealthy. An unreachable callback endpoint or a full callback queue will cause this error.
Get API status
GET /api/admin/v1/status/callback
Example request
$ curl 'http://localhost:8080/api/admin/v1/status/callback' -i -u '07a95e57-86a5-42df-b221-67f7dc131eca:B0EujseOpBrqqFL1Kwx1Aw==' -X GET
Example response - Status OK
HTTP/1.1 200 OK
X-Correlation-UUID: 428410a6-efbf-436f-a613-4c41ee974e85
Content-Type: application/json
Content-Length: 137

{
  "queues" : [ {
    "id" : "b6681be0-de6f-4f7d-95de-5d646219679c",
    "size" : 10,
    "status" : "OK"
  } ],
  "status_all" : "OK"
}
Example response - Status FAILURE
HTTP/1.1 200 OK
X-Correlation-UUID: 23a02ebf-b07a-4bf1-8349-1ea6216067af
Content-Type: application/json
Content-Length: 259

{
  "queues" : [ {
    "id" : "dc947d36-7eb7-414b-9da4-fb73164fd89c",
    "size" : 10000,
    "status" : "FAILURE",
    "error" : "Queue size is larger than limit (5000) for app-config: dc947d36-7eb7-414b-9da4-fb73164fd89c"
  } ],
  "status_all" : "FAILURE"
}