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:
-
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.
-
Authentication: Operations for executing secure mobile authentication requests via previously-enrolled device/application instances.
-
Device Management: Operations for the management of enrolled device/application instances, including locking/unlocking of instances and deactivation/un-enrollment.
-
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 |
---|---|
|
Used to retrieve a resource. |
|
Used to create a new resource. |
|
Full update of an existing resource. |
|
Partial update of an existing resource. |
|
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 |
---|---|
|
The request completed successfully |
|
A new resource has been created successfully. The resource’s URI is available from the response’s
|
|
An update to an existing resource has been applied successfully |
|
The request was malformed. The response body will include an error providing further information. |
|
Authentication/Authorization failed for the request |
|
Client not authorized to access the operation on the specified resource |
|
Resource with the given id does not exist |
|
Tried to create a resource that already exists |
|
Conditional request, but conditions not fulfilled |
|
Content well formed but content validation failed |
|
Conditional request required but no condition given |
|
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 |
---|---|---|
|
|
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 |
|
|
Unique code for this specific error type. More fine grained than the HTTP code, e.g. "AUTH_LEVEL_NOT_AVAILABLE_FOR_DEVICE" |
|
|
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" |
|
|
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 |
|
|
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 |
|
|
Array of field specific errors if there are any, typically used for validation faults (HTTP 422) |
Field specific error
Field | Type | Description |
---|---|---|
|
|
Field name if the error is related to a specific field |
|
|
Specific code for the error situation, e.g. "FIELD_TO_LONG" |
|
|
Human readable description of the error code, e.g. "Field allows max 255 characters" |
2.4.2. Error codes
Error code | Description |
---|---|
|
An unexpected error occurred |
|
Validation of request failed |
|
Resource does not exist |
|
Resource already exists |
|
Provided offset id does not exist |
|
Server was not able to parse the request |
|
Provided media type is not supported, server supports application/json |
|
Server does not accept the request |
|
Request is unauthorized |
|
Device is not registered |
|
Provided session expiry time exceeds the maximum allowed value |
|
Too many concurrent active activation sessions |
|
Server failed to create activation code |
|
No active sessions found for the device |
|
Device is locked. See device API for details |
|
Device is not locked |
|
Provided session is not an activation session |
|
Authentication level is not allowed |
|
Authentication method is not configured for this app config |
|
Authentication method and level does not match each other |
|
Authentication method is not activated for the device |
|
Provided session is not an authentication session |
|
Provided session is not an offline authentication session |
|
The purpose of the provided session is not supported |
|
The application configuration provided is not valid. |
|
The application ID was not found. |
|
The APNS key is used by one or more application configurations |
|
The End-to-End key has status ENABLED and is considered in use |
|
The patch request is not of a valid format and cannot be mapped to the object that is supposed to be updated. |
|
Authentication request has sendPush flag set to true, but nativePushEnabled option in app configuration is false. |
|
The session has expired and can no longer be used |
|
The session has already had a failed or successful outcome |
|
The session is cancelled and can no longer be used |
|
The specified authentication method is locked. If the method in question is an offline-method, other methods might still work. |
|
The authentication method you are trying to unlock is not locked |
|
Authentication method is required in the request |
|
The request is missing one or more request parameters |
|
The purpose of the given session is not perform recovery. |
|
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 |
---|---|
|
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 |
|
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 |
---|---|
|
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 |
---|---|
|
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 |
|
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 |
---|---|---|
|
|
Holds the url to the previous set of items |
|
|
Holds the url to the next set of items |
|
|
Offset as passed in request |
|
|
The number of items on each page |
|
|
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 |
---|---|---|
|
|
The name of the risk attribute |
|
|
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 |
---|---|---|---|---|
|
|
String |
A fingerprint of the operating system. This can be used for detecting whether the device is running a custom ROM or operating system |
|
|
|
String |
The operating system version. Examples: 4.1.2, 6.0.1 |
|
|
|
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 |
|
|
|
Boolean |
Indicate whether the application running can be debugged using a source level debugger, either by manifest entry or in emulator |
|
|
|
Boolean |
Indicate whether debug is enabled on device, either by user setting (USB-debugging enabled) or when running in emulator (debugging enabled by default) |
|
|
|
Boolean |
Indicate whether a debugger is connected to the application |
|
|
|
Boolean |
Indicate whether the application is running in an emulator |
|
|
|
Boolean |
Indicate whether the device has been rooted/jail-broken. For iOS this value has to be passed to Encap using the |
|
|
|
Boolean |
3.5 |
Indicate whether the device has secure screen enabled or not |
|
|
Boolean |
Indicate whether the device allows installation of applications outside the application store |
|
|
|
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. |
|
|
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. |
|
|
|
String |
HTTP User agent from smart device application. |
|
|
|
Base64 |
SHA256 hash of the unique hardware device ID of the client device. |
|
|
|
String |
The manufacturer of the device. Examples: "Apple", "Samsung". |
|
|
|
String |
The device’s model. Examples: "iPad2,2", "Nexus S". |
|
|
|
String |
Indicates the OperatingSystemType of the device, either Android or iOS. |
|
|
|
Base64 |
SHA256 hash of the application name. The server can use this for detecting re-packaging. |
|
|
|
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"}] |
|
|
String |
3.8 |
The status of the hardware protected key signature preformed by the Encap client SDK. |
|
|
String |
3.8 |
The result of the hardware protected key signature verification on the Encap server. |
|
|
Integer |
3.12 |
Provide battery level of the device. |
|
|
Boolean |
3.12 |
Indicate whether the device is being charged/connected to a charger. |
|
|
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:
|
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:
|
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 |
---|---|---|
|
|
Location accuracy |
|
|
Location altitude |
|
|
Location latitude |
|
|
Location longitude |
3.1.3. The operation context object
Field | Type | Description |
---|---|---|
|
|
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, that is base64 encoded twice. The double base64 encoding is a bug, the documentation will be updated once it’s fixed |
|
|
The MIME type of the content |
3.1.4. The session status object
Field | Type | Description |
---|---|---|
|
|
The status of the session. See session status for details. |
|
|
A description of the session status |
|
|
The state of the session. See session state for details. |
Session statuses
Session Status | Description |
---|---|
|
Operation is in progress |
|
Operation is authenticated, but not complete |
|
Operation has completed successfully |
|
Operation failed because the session was cancelled by the device |
|
Operation failed because the session was cancelled by the service provider |
|
Operation failed because the session was cancelled by the device. The device started a deactivation of authentication method(s) |
|
Operation failed because the session was cancelled when a new activation was started |
|
Operation failed because the session has expired |
|
Operation failed because the device is locked |
|
Operation failed because the device is locked by admin |
|
Operation failed because the device is locked by device verification |
|
Operation failed because the device is locked by pin verification |
|
Operation failed because the device is locked by incorrect salt key id |
|
Operation failed because the session callback failed. Legacy value from synchronous callback model. |
|
Operation failed because the device provided incorrect signed challenge |
|
Operation failed because the SafetyNet attestation validation failed |
|
Operation failed because the intermediate push attestation validation failed |
|
Operation failed because of missing intermediate push attestation details |
|
Operation failed because of missing SafetyNet attestation details |
|
Operation failed because authorization token validation failed |
|
Operation failed because the session was cancelled when recovery was started |
|
Operation failed because the recovery does not exist |
|
Operation failed because the recovery is locked |
|
Operation failed because the geofencing validation failed |
|
Operation failed because the App Attest validation failed |
|
Operation failed because of missing App Attest attestation details |
|
Operation failed because the Play Integrity validation failed |
|
Operation failed because of missing Play Integrity attestation details |
Session states
Session State | Description |
---|---|
|
Session is in progress |
|
Session has completed successfully |
|
Operation and session failed |
3.1.5. The attestation object
Field | Type | Description |
---|---|---|
|
|
Play Integrity attestation status for the device |
|
|
Date of when the Play Integrity attestation was performed |
|
|
SafetyNet attestation status for the device |
|
|
Date of when the SafetyNet attestation was performed |
|
|
App Attest attestation status for the device. Only for iOS devices |
|
|
Date of when the App Attest attestation was performed. Only for iOS devices |
App Attest statuses
App Attest status | Description |
---|---|
|
Attestation verification was successful |
|
Attestation failed because the Apple App Attest server was unavailable |
|
Attestation failed because App Attest is not supported on device |
|
Attestation failed because of an unexpected error; check the error message for details |
|
Attestation failed because the request took longer than the configured timeout |
|
Validation of the attestation object failed because the integrity check failed |
Play Integrity statuses
Google Play Integrity status | Description |
---|---|
|
Attestation verification was successful |
|
Attestation failed because the integrity check failed |
|
Attestation failed because the Google Play app is unrecognized |
|
Attestation failed because the Google Play app is unlicensed |
|
Attestation failed because of incorrect package name |
|
Attestation failed because of invalid JWS format |
|
Attestation failed because Google Play Integrity returned an API exception |
|
Attestation failed due to request taking longer than the configured timeout |
|
Attestation failed because of incorrect nonce |
|
Attestation failed because of missing JWS |
|
Attestation failed because of missing status returned from the client |
|
Attestation failed because the timestamp is not within the lifetime of the Encap server session |
|
Attestation failed due to client doesn’t have Google Play or the version is too old |
SafetyNet statuses
SafetyNet status | Description |
---|---|
|
Attestation verification was successful |
|
Attestation failed because the signature is invalid |
|
Attestation failed because the integrity check failed |
|
Attestation failed because of incorrect package name |
|
Attestation failed because of incorrect certificate digest |
|
Attestation failed because of invalid hostname |
|
Attestation failed because of invalid JWS format |
|
Attestation failed because SafetyNet returned an API exception |
|
Attestation failed due to request taking longer than the configured timeout |
|
Attestation failed due to missing API key |
|
Attestation failed because of incorrect nonce |
|
Attestation failed because of missing JWS |
|
Attestation failed because of missing status returned from the client |
|
Attestation failed because the timestamp is not within the lifetime of the session |
|
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 on ISO 3166-1 Alpha-2 format. |
|
|
Status of the geofencing client operation. |
|
|
Status of the geofencing server validation. |
Geofencing client statuses
Geofencing Client Status | Description |
---|---|
|
Country code obtained. |
|
Location not requested by app or user declined. |
|
Device did not obtain a location within configured accuracy before timeout. |
|
Location was mocked/faked. |
|
Geocoder not supported on device. |
|
Geocoder network or service not available. |
|
Unexpected geocoder error. |
|
Geocoder call did not finish within time limit. |
|
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 |
---|---|---|
|
|
Identifier of a given recovery. |
|
|
The recovery method used to set up the recovery. |
|
|
The recovery status of a given recovery. |
|
|
Date for when a given recovery was has been created. |
|
|
Date for when a given recovery has been updated. |
|
|
Date for when a given recovery has been used. |
Recovery status
Recovery status | Description |
---|---|
|
Recovery has been set up for the device and is ready to be used. |
|
Recovery has been deactivated. |
|
Recovery has been used to recover the device. |
|
Recovery has been locked. |
Recovery method
Recovery method | Description |
---|---|
|
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 |
|
|
PIN |
|
|
FaceID for iOS |
|
|
TouchID for iOS |
|
|
Fingerprint for Android |
|
|
TouchID for iOS where the registered fingerprints at activation time cannot be updated |
|
|
Biometric prompt for Android |
|
|
Device (offline authentication) |
|
|
PIN (offline authentication) |
|
|
TouchID for iOS (offline authentication) |
|
|
Biometric prompt for Android (offline authentication) |
|
|
Fingerprint for Android (offline authentication) |
|
|
FaceID for iOS (offline authentication) |
3.2.2. Authentication levels
Authentication level | Description |
---|---|
|
Authentication level for one factor |
|
Authentication level for two factors |
3.2.3. Lock reason
Lock reason | Description |
---|---|
|
Device is unlocked |
|
The verification of one of the authentication factors failed. Wrong device and/or a second-factor error (incorrect PIN code or biometrics) |
|
The device is locked by an administrative operation |
|
The verification of the device factor failed for an authentication |
|
The verification of the second authentication factor failed (incorrect PIN code or biometrics) |
|
The device provided an incorrect Salt-key ID during authentication |
|
The verification of the hardware-protected key failed (the key provided was incorrect) |
|
The device is locked due to a failed offline authentication, caused by OTP verification code mismatch |
|
The verification of the SafetyNet attestation failed |
|
The verification of the intermediate push attestation failed |
|
The verification of the App Attest attestation failed |
|
The verification of the Play Integrity attestation failed |
3.2.4. Session purpose
Purpose | Description |
---|---|
|
Activation/enrollment of new device. |
|
Authentication. |
|
Activating an additional auth method for an existing device. |
|
Deactivating an auth method for an existing device. |
|
Setting up recovery for an existing device. |
|
An existing recovery has been used to perform a recovery to a new device. |
|
An existing recovery has been deleted. |
|
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:


3.3.1. The enrollment object
Field | Type | Description |
---|---|---|
|
|
The UUID for the enrollment session |
|
|
The code to use for activation |
|
|
The application ID for the device |
|
|
The callback address for the device |
|
|
The UUID for the device |
|
|
The time for when the session was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC' |
|
|
The time for when the session will expire. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC' |
|
|
The authentication level of the enrollment. See authentication levels for options |
|
|
List of activated authentication methods (Variant 2). See authentication methods for possible values |
|
|
The push address for the device, this address is used when sending push to the device using FCM or APNS. |
|
|
A custom payload send to the device in the push notification. |
|
|
Explicit setting for the device to lock/unlock recovery. Introduced in Encap 3.13 |
|
|
Operation context object that contains details to be shown after a successful the authentication. See operation_context object for details. |
|
|
Attestation object that contains details for all the attestations performed for the device. See attestation object for details. |
|
|
List that contains name and value for all risk attributes. See risk_attributes object for details. |
|
|
Status object that contains status details of the session. See session_status object for details. |
|
|
Location object that contains location details, see location object for details. |
|
|
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 |
---|---|---|---|
|
|
Yes |
The application id for the configuration to use during the enrollment |
|
|
No |
The authentication level for the operation. See authentication levels for options. If not provided default level TWO_FACTOR will be used |
|
|
No |
The callback address for the device |
|
|
No |
Life time in ms for for the session before it expires |
|
|
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. |
|
|
No |
Allows to override recovery setting from app config and disable recovery during REST enrollment. Introduced in Encap 3.13. |
|
|
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.

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 |
---|---|---|---|
|
|
Yes |
The device id for the configuration to use during the re-enrollment |
|
|
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. |
|
|
No |
The authentication level for the operation. See authentication levels for options. If not provided default level TWO_FACTOR will be used |
|
|
No |
The callback address for the device |
|
|
No |
Life time in ms for for the session before it expires |
|
|
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. |
|
|
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:


3.4.1. The authentication object
Field | Type | Description |
---|---|---|
|
|
The UUID for the authentication session |
|
|
The authentication level of the enrollment. See authentication levels for options |
|
|
The authentication method for the operation (Variant 1). See authentication methods for possible values |
|
|
The callback address for the device |
|
|
The UUID for the device |
|
|
Boolean for if a push has been sent or not |
|
|
The time for when the session was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC' |
|
|
The time for when the session will expire. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC' |
|
|
The purpose of the session. See session purpose for details. |
|
|
The base64 encoded client data used by the client in identify. |
|
|
A custom payload send to the device in the push notification. |
|
|
Operation context object that contains details to be shown before the authentication.See operation_context object for details. |
|
|
Operation context object that contains details to be shown after a successful the authentication. See operation_context object for details. |
|
|
List that contains name and value for all risk attributes. See risk_attributes object for details. |
|
|
Location object that contains location details, see location object for details. |
|
|
Status object that contains status details of the session. See session_status object for details. |
|
|
Attestation object that contains details for all the attestations performed for the device. See attestation object for details. |
|
|
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 |
---|---|---|---|
|
|
Yes |
The UUID for the device |
|
|
No |
The authentication level for the operation. See authentication levels for options. If not provided default level TWO_FACTOR will be used |
|
|
No |
The authentication method for the operation (Variant 1). See authentication methods for possible values |
|
|
No |
The callback address for the device |
|
|
No |
Life time in ms for for the session before it expires |
|
|
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. |
|
|
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. |
|
|
No |
Operation context object that contains details to be shown before the authentication.See operation_context object for details. |
|
|
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:

3.5.1. The offline authentication object
Field | Type | Description |
---|---|---|
|
|
The UUID of the authentication session |
|
|
The context used in the authentication |
|
|
String of data transferable to the client to complete the authentication |
|
|
The UUID for the device |
|
|
The time for when the session was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC' |
|
|
The time for when the session will expire. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC' |
|
|
The authentication method for the operation (Variant 1). See authentication methods for possible values |
|
|
The authentication level of the enrollment. See authentication levels for options |
|
|
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 |
---|---|---|---|
|
|
Yes |
The UUID of the device you want to authenticate |
|
|
No |
Amount of time until the authentication will expire in milliseconds |
|
|
No |
Authentication method you want to use (Variant 1). See authentication methods for possible values |
|
|
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 |
---|---|---|---|
|
|
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 |
---|---|---|
|
|
The result of the authentication. See offline verification status for possible values. |
|
|
Number of attempts before the authentication method gets locked |
Verification status values
Status | Description |
---|---|
|
Operation has completed successfully |
|
Operation failed because the session was cancelled by the device |
|
Operation failed because the session has expired |
|
Operation failed because the device is locked |
|
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 |
---|---|---|
|
|
The UUID for the device |
|
|
The application ID for the device |
|
|
The client API version used in the device’s last operation |
|
|
The client API version that the device was originally activated on |
|
|
Encap server release version that the device was originally activated on |
|
|
SHA256 hash of the unique hardware device ID of the client device. |
|
|
SHA256 hash of the device client salt. |
|
|
The operating system type of the device |
|
|
List of activated authentication methods (Variant 2). See authentication methods for possible values |
|
|
The time for when the device was originally activated |
|
|
The time for when the device last made an operation |
|
|
An lock object containing lock details. Only present when the device is locked |
|
|
The reference url for the lock |
|
|
List containing all reasons for the device lock. See lock reason for possible values. |
|
|
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 |
|
|
List of all recoveries for the device. See recovery object for details. Introduced in Encap 3.13 |
|
|
Explicit setting for the device to lock/unlock recovery. Introduced in Encap 3.13 |
|
|
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
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 |
---|---|---|
|
|
The UUID for the session |
|
|
Link to authentication object for the session |
|
|
The purpose of the session. See session purpose for details. |
|
|
The state of the session |
|
|
The date for when the session was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC' |
|
|
The date for when the session expires. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC' |
|
|
True if this is an offline authentication session |
|
|
True if the session was run in client only mode |
|
|
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 |
---|---|---|
|
|
The UUID for the device |
|
|
An lock object containing lock details |
|
|
The reference url for the lock |
|
|
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.
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
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 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 |
---|---|---|
|
|
The UUID for the recovery session |
|
|
The application ID for the device |
|
|
The UUID for the device |
|
|
The time for when the session was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC' |
|
|
The time for when the session will expire. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC' |
|
|
The purpose of the session. See session purpose for details. |
|
|
List of activated authentication methods (Variant 2). See authentication methods for possible values |
|
|
List that contains name and value for all risk attributes. See risk_attributes object for details. |
|
|
Location object that contains location details, see location object for details. |
|
|
Status object that contains status details of the session. See session_status object for details. |
|
|
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 |
---|---|---|
|
|
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
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 |
---|---|---|
|
|
Geofencing enforcement mode (OFF/OPTIONAL/REQUIRED) |
|
|
Comma separated list of continents in which authentication is allowed (AF/NA/OC/AN/AS/EU/SA) |
|
|
Comma separated list of countries in which authentication is allowed (in addition to allowed continents). ISO 3166-1 alpha-2 standard. |
|
|
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 |
---|---|---|
|
|
Indicates if the API is in a "healthy" state |
|
|
An RFC 3339 formatted date and time in UTC |
|
|
Array of underlying dependencies and their status. Only included if request is authenticated |
|
|
Indicates if this dependency is in a "healthy" state |
|
|
Time in milliseconds it took to check this dependency |
|
|
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 |
---|---|---|
|
|
The logical name of the application configuration |
|
|
The unique ID of this application configuration registration. This value is central to these APIs |
|
|
Reference to the APNS push certificate or token. |
|
|
The human readable name for the application configuration |
|
|
The application configuration parameters |
4.2.2. The configuration object
This object contains the configuration parameters and their value
Parameter | Description | Allowed values | Default |
---|---|---|---|
|
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 |
|
The length in characters of the activation code that should be generated. |
4 .. MAXINT |
6 |
|
The type of characters that can be used during the generation of the activation code. |
ALPHA, ALPHANUMERIC, ANY, NUMERIC |
NUMERIC |
|
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 |
|
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 |
|
The grace amount of failed DEVICE_PIN (or offline) authentications for any client before they are locked out. |
0..MAXINT |
3 |
|
The APN server configuration that defines where to reach the APNs. |
PRODUCTION, SANDBOX |
PRODUCTION |
|
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 |
|
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 |
|
|
Enable notification sound for push messages to iOS devices. |
true, false |
false |
|
Sets the interruption level for push messages to iOS devices to "time-sensitive". |
true, false |
false |
|
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 |
|
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 |
|
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 |
|
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 Cloud Messaging. The URL of your Firebase database (as shown in the Firebase project settings). |
String |
|
|
Firebase Cloud Messaging. The contents of the serviceAccount.json (credentials file) for your Firebase Cloud Messaging project. |
String |
|
|
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 |
|
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 |
|
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 |
|
The maximum amount of time (in milliseconds) the sessionExpiry can be set to. |
1..MAXINT |
300000 |
|
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 |
|
The same as MINIMUM_REQUIRED_ENCAP_API_VERSION_ANDROID, but applies to iOS clients. |
Semantic version, ex: "3.7.0" |
null |
|
Enable the server to send push messages with Fire Cloud Messaging or Apple APNS |
true, false |
false |
|
Enable users to set up recovery with an alternative set of user credentials |
true, false |
false |
|
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 |
|
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 |
|
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 |
|
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 in milliseconds. After this time, the token will not be valid anymore. |
0..MAXINT |
300000 |
|
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 |
|
List of continents in which activation is allowed. |
2 letter continent codes (AF/NA/OC/AN/AS/EU/SA), in a comma separated list. |
|
|
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. |
|
|
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 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 |
|
List of continents in which authentication is allowed. |
2 letter continent codes (AF/NA/OC/AN/AS/EU/SA), in a comma separated list. |
|
|
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. |
|
|
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. |
|
|
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 |
|
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 When not specifying an API the callback for the event will be sent regardless of API. e.g. DEVICE_LOCKED, DEVICE_DEACTIVATED:[REST] Format specification: <event-type-1>[:< [api-1|api-2|…] >], <event-type-2>[:< [api-1|api-2|…] >] |
Allowed events: See event-callback-events |
|
|
The URL that should receive callbacks in case any callback events have been configured for this app-config. |
String |
|
|
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 |
|
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
|
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 |
|
|
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 |
|
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 |
|
|
Play Integrity attestation decryption key, used to decrypt the integrity token. Required if ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE is REQUIRED or OPTIONAL. |
Base64 |
|
|
Play Integrity attestation verification key, used to validate the integrity token. Required if ATTESTATION_ANDROID_PLAY_INTEGRITY_MODE is REQUIRED or OPTIONAL. |
Base64 |
|
|
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 |
|
|
SafetyNet Attestation, the APK certificate SHA-256 digest. Base64 encoded SHA-256. Required if ATTESTATION_ANDROID_SAFETYNET_MODE is REQUIRED or OPTIONAL. |
Base64 |
|
|
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 |
|
The environment for an app that uses the App Attest service to validate itself. |
DEVELOPMENT, PRODUCTION |
PRODUCTION |
|
iOS app attestation timeout, after this time, in milliseconds, the attestation request will time out. |
1..MAXINT |
20000 |
|
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 |
|
|
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 |
|
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 |
|
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 |
---|---|---|---|
|
|
Yes |
The logical name of the application configuration |
|
|
No |
The UUID of the APNs push certificate or token used. Required if NATIVE_PUSH_ENABLED is true. |
|
|
No |
The human readable name for the application configuration |
|
|
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 |
---|---|---|---|
|
|
No |
The status of the application configuration. ENABLED, DISABLED. |
|
|
No |
The UUID of the APNs push certificate or token used. Required if NATIVE_PUSH_ENABLED is true. |
|
|
No |
The human readable name for the application configuration |
|
|
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 |
---|---|---|
|
|
The UUID for the APNS certificate |
|
|
The name of the APNS certificate |
|
|
The SHA1 hash of the APNS certificate |
|
|
The SHA256 hash of the APNS certificate |
|
|
The description of the APNS certificate |
|
|
The start date of the certificate validity period |
|
|
The end date of the certificate validity period |
|
|
The subject distinguished name from the certificate |
|
|
The issuer distinguished name from the certificate |
|
|
The name/id of the creator of the APNS certificate |
|
|
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 |
---|---|---|---|
|
|
Yes |
The name of the APNS certificate |
|
|
No |
The description of the APNS certificate |
|
|
Yes |
The Base64 encoded string of the APNS certificate bytes |
|
|
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 |
---|---|---|
|
|
The UUID for the APNs token |
|
|
The name of the APNs token |
|
|
The SHA1 hash of the APNs token |
|
|
The SHA256 hash of the APNs token |
|
|
The description of the APNs token |
|
|
Key ID of the APNs token |
|
|
Team ID of Apple Developer Account |
|
|
The name/id of the creator of the APNs token |
|
|
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 |
---|---|---|---|
|
|
Yes |
The name of the APNs token |
|
|
No |
The description of the APNs token |
|
|
Yes |
The Base64 encoded string of APNs token private key |
|
|
Yes |
Key ID of the APNs token |
|
|
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 |
---|---|---|
|
|
The API key ID, UUID, for the key. |
|
|
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 |
|
|
The description for the API key |
|
|
The name/id of the creator of the API key |
|
|
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 |
---|---|---|---|
|
|
No |
The description for the API key |
Returns
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
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 |
---|---|---|
|
|
The UUID for the End-To-End key |
|
|
Name for the End-To-End key |
|
|
Description for the End-To-End key |
|
|
The name/id of the creator of the End-To-End key |
|
|
The date for when the End-To-End key was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC' |
|
|
The SHA256 hash of the End-To-End key certificate |
|
|
Base64 encoded End-To-End key certificate |
|
|
The UUID for the organization that owns this End-To-End key |
|
|
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 |
---|---|---|---|
|
|
Yes |
The name of the End-To-End key |
|
|
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 |
---|---|---|---|
|
|
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 |
---|---|---|
|
|
The id of the statistics record |
|
|
Status of the statistics record. May be IN_PROGRESS, READY or FAILED |
|
|
UUID of the app config the statistics are generated for |
|
|
Registrations used after the number of days from this field will be included in the statistic |
|
|
The time the record was first created |
|
|
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 |
|
|
Number of devices on this version |
5.1.3. Request statistics
POST /api/statistics/v1/encap-client-versions
Arguments
Path | Type | Required | Description |
---|---|---|---|
|
|
Yes |
UUID of the app config the statistics are generated for |
|
|
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 (status SUCCESS) |
|
Device unlocked (status SUCCESS) |
|
Device deactivated (status SUCCESS) |
|
Device activation session completed (status SUCCESS or FAILURE) |
|
Device authentication session completed (status SUCCESS or FAILURE) |
Event APIs
API type | Description |
---|---|
|
Event for operations initiated by the mobile device |
|
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 |
---|---|---|---|
|
|
Yes |
Unique event ID. Can be used to identify duplicate callbacks for the same event (rare state) |
|
|
Yes |
The type of event that has occurred. See event-callback-events for possible values |
|
|
Yes |
The UUID of the owning app-config for this device |
|
|
Yes |
The UUID of the device that is affected by or has caused the event |
|
|
No |
The UUID of the session that this event belongs to (if any) |
|
|
No |
Status of the current event (SUCCESS or FAILURE) |
|
|
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 |
---|---|---|
|
|
Overall queue health status |
|
|
List of event callback queues |
Queue details status object
Field | Type | Description |
---|---|---|
|
|
App-config id for the event callback queue |
|
|
Number of items in events callback queue |
|
|
Health status of the queue |
|
|
If 'status' is FAILURE, the error field should contain details about the failure |
Event-callback queue status
Status | Description |
---|---|
|
Queue health status is OK |
|
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"
}