Encap Server Administrator API Guide v1

1. Overview

The Encap Server Administrator REST APIs are created for Server administrators, to enable management of the server and resources that are shared across organizations.

2. Common concepts

2.1. REST API 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.

For Encap Server Administration REST APIs it’s required that the API key used for authentication is owned by the ADMIN organization.

GET /api/smart-device/v1/authentications/cd7cc4ad-4def-4555-b859-6791826d7665 HTTP/1.1
Authorization: Basic MTQ4NzRjZjItYzBiMC00YWYyLThjOTYtNWNmNTYxNDEzOTYxOjFzVk4vY0tSTlJaSmcxQWJDQkNmRmc9PQ==
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

Verb	Usage
`GET`	Used to retrieve a resource.
`POST`	Used to create a new resource.
`PUT`	Full update of an existing resource.
`PATCH`	Partial update of an existing resource.
`DELETE`	Used to delete an existing resource.

GET

Used to retrieve a resource.

POST

Used to create a new resource.

PUT

Full update of an existing resource.

PATCH

Partial update of an existing resource.

DELETE

Used to delete an existing resource.

2.3. HTTP status codes

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

Status code Usage

Status code	Usage
`200 OK`	The request completed successfully
`201 Created`	A new resource has been created successfully. The resource’s URI is available from the response’s `Location` header
`204 No Content`	An update to an existing resource has been applied successfully
`400 Bad Request`	The request was malformed. The response body will include an error providing further information.
`401 Unauthorized`	Authentication/Authorization failed for the request
`403 Forbidden`	Client not authorized to access the operation on the specified resource
`404 Not Found`	Resource with the given id does not exist
`409 Conflict`	Tried to create a resource that already exists
`412 Precondition Failed`	Conditional request, but conditions not fulfilled
`422 Unprocessable Entity`	Content well formed but content validation failed
`428 Precondition Required`	Conditional request required but no condition given
`500 Internal Server Error`	Unexpected failure on server side

200 OK

The request completed successfully

201 Created

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

204 No Content

An update to an existing resource has been applied successfully

400 Bad Request

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

401 Unauthorized

Authentication/Authorization failed for the request

403 Forbidden

Client not authorized to access the operation on the specified resource

404 Not Found

Resource with the given id does not exist

409 Conflict

Tried to create a resource that already exists

412 Precondition Failed

Conditional request, but conditions not fulfilled

422 Unprocessable Entity

Content well formed but content validation failed

428 Precondition Required

Conditional request required but no condition given

500 Internal Server Error

Unexpected failure on server side

2.4. Errors

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

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

2.4.1. The error object

The error entity has the following response structure:

Field Type Description

Field	Type	Description
`status`	`Number`	Holds a duplicate copy of the HTTP error status code for convenience, so that clients can “see” it without having to analyze the response’s header
`code`	`String`	Unique code for this specific error type. More fine grained than the HTTP code, e.g. "AUTH_LEVEL_NOT_AVAILABLE_FOR_DEVICE"
`message`	`String`	Short description of the error, what might have cause it and possibly a “fixing” proposal, e.g. "Device is not activated for 2FA authentication, activate the device for 2FA before trying to use it for 2FA authentication"
`correlation_id`	`String`	The correlation ID sent in the request or generated on the server. Will contain the same value as the response header X-Correlation-UUID. Can be used to find the correlating error messages from the server log
`developer_message`	`String`	Detailed message, containing additional data that might be relevant to the developer. Only provided when development mode is switched on and can potentially contain stack trace information or similar
`errors`	`Array`	Array of field specific errors if there are any, typically used for validation faults (HTTP 422)

status

Number

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

code

String

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

message

String

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

correlation_id

String

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

developer_message

String

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

errors

Array

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

Field specific error

Field Type Description

Field	Type	Description
`field`	`String`	Field name if the error is related to a specific field
`code`	`String`	Specific code for the error situation, e.g. "FIELD_TO_LONG"
`message`	`String`	Human readable description of the error code, e.g. "Field allows max 255 characters"

field

String

Field name if the error is related to a specific field

code

String

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

message

String

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

2.4.2. Error codes

Error code Description

Error code	Description
`REST_UNEXPECTED`	An unexpected error occurred
`REST_VALIDATION_FAULT`	Validation of request failed
`REST_RESOURCE_NOT_FOUND`	Resource does not exist
`REST_RESOURCE_ALREADY_EXISTS`	Resource already exists
`REST_PAGINATION_OFFSET_NOT_FOUND`	Provided offset id does not exist
`REST_HTTP_MESSAGE_NOT_READABLE`	Server was not able to parse the request
`REST_UNSUPPORTED_MEDIA_TYPE`	Provided media type is not supported, server supports application/json
`REST_NOT_ACCEPTABLE`	Server does not accept the request
`REST_UNAUTHORIZED`	Request is unauthorized
`REST_ADMIN_ORGANIZATION_NOT_ALLOWED_TO_DELETE`	Cannot delete an organization with type ADMIN
`REST_ORGANIZATION_HAS_ACTIVE_RESOURCES`	The organization has active resources and cannot be deleted. Active resources are of type APNS certificate, API Key and/or End-to-End Key and must be deleted before removing the organization.

REST_UNEXPECTED

An unexpected error occurred

REST_VALIDATION_FAULT

Validation of request failed

REST_RESOURCE_NOT_FOUND

Resource does not exist

REST_RESOURCE_ALREADY_EXISTS

Resource already exists

REST_PAGINATION_OFFSET_NOT_FOUND

Provided offset id does not exist

REST_HTTP_MESSAGE_NOT_READABLE

Server was not able to parse the request

REST_UNSUPPORTED_MEDIA_TYPE

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

REST_NOT_ACCEPTABLE

Server does not accept the request

REST_UNAUTHORIZED

Request is unauthorized

REST_ADMIN_ORGANIZATION_NOT_ALLOWED_TO_DELETE

Cannot delete an organization with type ADMIN

REST_ORGANIZATION_HAS_ACTIVE_RESOURCES

The organization has active resources and cannot be deleted. Active resources are of type APNS certificate, API Key and/or End-to-End Key and must be deleted before removing the organization.

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: 15eb40a8-b0c7-4b66-95a6-6e12a1768911
Content-Type: application/json
Content-Length: 13970

{
  "status" : 422,
  "code" : "REST_VALIDATION_FAULT",
  "message" : "Parameter validation failed on request /smart-device/v1/devices/0f7cd0a7-879f-49a6-92b8-6dab6abc94db/sessions. For more information see field specific errors.",
  "correlation_id" : "15eb40a8-b0c7-4b66-95a6-6e12a1768911",
  "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"
  } ],
  "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:158)\n\tat org.springframework.web.method.support.HandlerMethodArgumentResolverComposite.resolveArgument(HandlerMethodArgumentResolverComposite.java:122)\n\tat org.springframework.web.method.support.InvocableHandlerMethod.getMethodArgumentValues(InvocableHandlerMethod.java:224)\n\tat org.springframework.web.method.support.InvocableHandlerMethod.invokeForRequest(InvocableHandlerMethod.java:178)\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:926)\n\tat org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter.handleInternal(RequestMappingHandlerAdapter.java:831)\n\tat org.springframework.web.servlet.mvc.method.AbstractHandlerMethodAdapter.handle(AbstractHandlerMethodAdapter.java:87)\n\tat org.springframework.web.servlet.DispatcherServlet.doDispatch(DispatcherServlet.java:1089)\n\tat org.springframework.web.servlet.DispatcherServlet.doService(DispatcherServlet.java:979)\n\tat org.springframework.web.servlet.FrameworkServlet.processRequest(FrameworkServlet.java:1014)\n\tat org.springframework.web.servlet.FrameworkServlet.doGet(FrameworkServlet.java:903)\n\tat jakarta.servlet.http.HttpServlet.service(HttpServlet.java:633)\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:723)\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.DirectMethodHandleAccessor.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:775)\n\tat org.junit.platform.commons.support.ReflectionSupport.invokeMethod(ReflectionSupport.java:479)\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:161)\n\tat org.junit.jupiter.engine.extension.TimeoutExtension.interceptTestableMethod(TimeoutExtension.java:152)\n\tat org.junit.jupiter.engine.extension.TimeoutExtension.interceptTestMethod(TimeoutExtension.java:91)\n\tat org.junit.jupiter.engine.execution.InterceptingExecutableInvoker$ReflectiveInterceptorCall.lambda$ofVoidMethod$0(InterceptingExecutableInvoker.java:112)\n\tat org.junit.jupiter.engine.execution.InterceptingExecutableInvoker.lambda$invoke$0(InterceptingExecutableInvoker.java:94)\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:93)\n\tat org.junit.jupiter.engine.execution.InterceptingExecutableInvoker.invoke(InterceptingExecutableInvoker.java:87)\n\tat org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.lambda$invokeTestMethod$7(TestMethodTestDescriptor.java:216)\n\tat org.junit.platform.engine.support.hierarchical.ThrowableCollector.execute(ThrowableCollector.java:73)\n\tat org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.invokeTestMethod(TestMethodTestDescriptor.java:212)\n\tat org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.execute(TestMethodTestDescriptor.java:137)\n\tat org.junit.jupiter.engine.descriptor.TestMethodTestDescriptor.execute(TestMethodTestDescriptor.java:69)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$6(NodeTestTask.java:156)\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:146)\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:144)\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:143)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.execute(NodeTestTask.java:100)\n\tat org.junit.platform.engine.support.hierarchical.ForkJoinPoolHierarchicalTestExecutorService$ExclusiveTask.exec(ForkJoinPoolHierarchicalTestExecutorService.java:274)\n\tat java.base/java.util.concurrent.ForkJoinTask.doExec(Unknown Source)\n\tat java.base/java.util.concurrent.ForkJoinPool$WorkQueue.tryRemoveAndExec(Unknown Source)\n\tat java.base/java.util.concurrent.ForkJoinTask.awaitDone(Unknown Source)\n\tat java.base/java.util.concurrent.ForkJoinTask.join(Unknown Source)\n\tat org.junit.platform.engine.support.hierarchical.ForkJoinPoolHierarchicalTestExecutorService.joinConcurrentTasksInReverseOrderToEnableWorkStealing(ForkJoinPoolHierarchicalTestExecutorService.java:201)\n\tat org.junit.platform.engine.support.hierarchical.ForkJoinPoolHierarchicalTestExecutorService.invokeAll(ForkJoinPoolHierarchicalTestExecutorService.java:167)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$6(NodeTestTask.java:160)\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:146)\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:144)\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:143)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.execute(NodeTestTask.java:100)\n\tat org.junit.platform.engine.support.hierarchical.ForkJoinPoolHierarchicalTestExecutorService$ExclusiveTask.exec(ForkJoinPoolHierarchicalTestExecutorService.java:274)\n\tat java.base/java.util.concurrent.ForkJoinTask.doExec(Unknown Source)\n\tat java.base/java.util.concurrent.ForkJoinPool$WorkQueue.tryRemoveAndExec(Unknown Source)\n\tat java.base/java.util.concurrent.ForkJoinTask.awaitDone(Unknown Source)\n\tat java.base/java.util.concurrent.ForkJoinTask.join(Unknown Source)\n\tat org.junit.platform.engine.support.hierarchical.ForkJoinPoolHierarchicalTestExecutorService.joinConcurrentTasksInReverseOrderToEnableWorkStealing(ForkJoinPoolHierarchicalTestExecutorService.java:201)\n\tat org.junit.platform.engine.support.hierarchical.ForkJoinPoolHierarchicalTestExecutorService.invokeAll(ForkJoinPoolHierarchicalTestExecutorService.java:167)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.lambda$executeRecursively$6(NodeTestTask.java:160)\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:146)\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:144)\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:143)\n\tat org.junit.platform.engine.support.hierarchical.NodeTestTask.execute(NodeTestTask.java:100)\n\tat org.junit.platform.engine.support.hierarchical.ForkJoinPoolHierarchicalTestExecutorService$ExclusiveTask.exec(ForkJoinPoolHierarchicalTestExecutorService.java:274)\n\tat java.base/java.util.concurrent.ForkJoinTask.doExec(Unknown Source)\n\tat java.base/java.util.concurrent.ForkJoinPool$WorkQueue.topLevelExec(Unknown Source)\n\tat java.base/java.util.concurrent.ForkJoinPool.scan(Unknown Source)\n\tat java.base/java.util.concurrent.ForkJoinPool.runWorker(Unknown Source)\n\tat java.base/java.util.concurrent.ForkJoinWorkerThread.run(Unknown Source)\n"
}

2.5. Headers

2.5.1. Request header

Name Description

Name	Description
`X-Correlation-UUID`	Optional request header with a UUID for the request, if not present the server will generate a UUID. If the provided UUID is invalid server will respond with HTTP code 400
`Authorization`	Authentication is performed via HTTP Basic Auth, and an API key is provided as the basic auth username value and the API secret as the password value, username and password is expected to be separated with a ':'. This header is required.

X-Correlation-UUID

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

Authorization

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

2.5.2. Response header

Every response has the following header(s):

Name Description

Name	Description
`X-Correlation-UUID`	A UUID for the request. Id can be provided in the request header, if not provided it will be generated by the server

X-Correlation-UUID

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

2.6. Pagination

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

2.6.1. Request

Pagination requests has the following request parameters:

Parameter Description

Parameter	Description
`offset`	Id of the first session to include in response. Offset is optional, if not provided the result will start with the first session in the device history
`limit`	The number of objects on each page. Limit is optional, if not provided the defualt of 100 will be used.

offset

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

limit

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

2.6.2. Response

Pagination response has the following structure:

Field Type Description

Field	Type	Description
`previous`	`String`	Holds the url to the previous set of items
`next`	`String`	Holds the url to the next set of items
`offset`	`String`	Offset as passed in request
`limit`	`Number`	The number of items on each page
`items`	`Array`	Items contains a list of the paginated objects for the request

previous

String

Holds the url to the previous set of items

next

String

Holds the url to the next set of items

offset

String

Offset as passed in request

limit

Number

The number of items on each page

items

Array

Items contains a list of the paginated objects for the request

Example of pagination response:

HTTP/1.1 200 OK
X-Correlation-UUID: 7ef78cd4-74c5-44aa-8e87-eceaa4218062
Content-Type: application/json
Content-Length: 1541

{
  "previous" : "/smart-device/v1/devices/92c478fc-82d1-48b2-8f91-75c830995d74/sessions?limit=3&offset=dff3245b-6385-47cb-90dd-37166f3ab38c",
  "next" : "/smart-device/v1/devices/92c478fc-82d1-48b2-8f91-75c830995d74/sessions?limit=3&offset=e8839236-31bd-461d-af20-f05fe68be14d",
  "offset" : "5045a14c-6ad3-415a-a079-b87916867a16",
  "limit" : 3,
  "items" : [ {
    "session_id" : "3a30b6f6-64f6-42cd-80cc-fbd2bfbdbfdd",
    "device_id" : "3826d15c-21a4-4d9c-9d48-3ce9ed43a88d",
    "ref" : "/enrollments/3a30b6f6-64f6-42cd-80cc-fbd2bfbdbfdd",
    "purpose" : "ACTIVATION",
    "state" : "SUCCESS",
    "client_only" : false,
    "session_created_on" : "2025-03-17T16:58:08.097UTC",
    "session_expires_on" : "2025-03-17T16:58:08.097UTC",
    "offline" : false
  }, {
    "session_id" : "e93c4c18-23cc-461f-b66c-a04e65a91328",
    "device_id" : "3826d15c-21a4-4d9c-9d48-3ce9ed43a88d",
    "ref" : "/authentications/e93c4c18-23cc-461f-b66c-a04e65a91328",
    "purpose" : "AUTHENTICATION",
    "state" : "IN_PROGRESS",
    "client_only" : false,
    "session_created_on" : "2025-03-17T16:58:08.097UTC",
    "session_expires_on" : "2025-03-17T16:58:08.097UTC",
    "offline" : false
  }, {
    "session_id" : "f1140d34-9c21-4ff2-8d39-4cec8f84ef27",
    "device_id" : "3826d15c-21a4-4d9c-9d48-3ce9ed43a88d",
    "purpose" : "DELETE_RECOVERY",
    "state" : "IN_PROGRESS",
    "client_only" : false,
    "session_created_on" : "2025-03-17T16:58:08.097UTC",
    "session_expires_on" : "2025-03-17T16:58:08.097UTC",
    "offline" : false
  } ]
}

3. Manage API

3.1. Organization

An API for maintaining Organizations.

3.1.1. The Organization object

Field Type Description

Field	Type	Description
`id`	`UUID`	The UUID for the organization
`description`	`String`	The description for the organization
`type`	`String`	The type of organization, ADMIN or STANDARD
`created_at`	`String`	The time for when the organization was created
`created_by`	`String`	The name/id of the creator of the organization
`generated_type`	`String`	Type of how the organization was created

id

UUID

The UUID for the organization

description

String

The description for the organization

type

String

The type of organization, ADMIN or STANDARD

created_at

String

The time for when the organization was created

created_by

String

The name/id of the creator of the organization

generated_type

String

Type of how the organization was created

Generated type values

Value Description

Value	Description
`WEB`	Created with the Admin Web UI.
`COMMAND_LINE`	Created with the command line scripts.
`ENCAP_SERVER`	Created implicitly by an action on the Encap Server.
`MIGRATION_JOB`	Created by the DB upgrade scripts.
`REST_API`	Created with the REST API.

WEB

Created with the Admin Web UI.

COMMAND_LINE

Created with the command line scripts.

ENCAP_SERVER

Created implicitly by an action on the Encap Server.

MIGRATION_JOB

Created by the DB upgrade scripts.

REST_API

Created with the REST API.

3.1.2. Create Organization

POST /admin-api/manage/v1/organizations

Creates a new Organization with the provided values. For an organization to be usable by any client side applications, you need at least one application configuration and one End-to-End Key.

See Application configuration and End-to-End Key for details.

Arguments

Path Type Required Description

Path	Type	Required	Description
`description`	`String`	No	Description for the organization

description

String

Description for the organization

Returns

Returns an organization object if the request is processed successfully, and returns an error otherwise.

Example request

$ curl 'http://localhost:8080/admin-api/manage/v1/organizations' -i -u '85d8884c-c1f2-4bd1-b46c-0f0af07ae77a:3YBA6sfr+ukblV/aipnXpg==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "description" : "Organization ABC"
}'

Example response

HTTP/1.1 201 Created
X-Correlation-UUID: e40d75c0-7cf4-4eb9-8955-1d489038945a
Location: /manage/v1/organizations/7bbb9db4-ee30-4dc8-b0bd-c1dc2b746cb6
Content-Type: application/json
Content-Length: 249

{
  "id" : "7bbb9db4-ee30-4dc8-b0bd-c1dc2b746cb6",
  "description" : "Organization ABC",
  "type" : "STANDARD",
  "created_at" : "2025-03-17T16:58:07.949UTC",
  "created_by" : "85d8884c-c1f2-4bd1-b46c-0f0af07ae77a",
  "generated_type" : "REST_API"
}

3.1.3. Get all organizations

GET /admin-api/manage/v1/organizations?limit=10&offset=0

Returns a pagination object with a list of organization objects.

Example request

$ curl 'http://localhost:8080/admin-api/manage/v1/organizations?limit=10' -i -u '85d8884c-c1f2-4bd1-b46c-0f0af07ae77a:3YBA6sfr+ukblV/aipnXpg==' -X GET

Example response

HTTP/1.1 200 OK
X-Correlation-UUID: a3467e57-c7e1-4438-8dda-9642f0f641e6
Content-Type: application/json
Content-Length: 831

{
  "limit" : 10,
  "items" : [ {
    "id" : "3ed55b7f-9cda-4ae6-955c-c5a98a209b10",
    "description" : "The admin organization",
    "type" : "ADMIN",
    "created_at" : "2025-03-17T15:34:47.532UTC",
    "created_by" : "encap",
    "generated_type" : "ENCAP_SERVER"
  }, {
    "id" : "1a6aad55-2ae6-460d-9ae3-997acc792cd4",
    "description" : "The standard organization abc",
    "type" : "STANDARD",
    "created_at" : "2025-03-17T16:58:07.532UTC",
    "created_by" : "e5a6f838-4c10-4201-9e18-e22490924c38",
    "generated_type" : "REST_API"
  }, {
    "id" : "91fdf633-e43c-4dea-bf70-09c19f49cc1e",
    "description" : "The standard organization xyz",
    "type" : "STANDARD",
    "created_at" : "2025-03-17T16:58:07.532UTC",
    "created_by" : "aa621441-804c-4237-b58b-2c6527bdd6b2",
    "generated_type" : "REST_API"
  } ]
}

3.1.4. Delete organization

DELETE /admin-api/manage/v1/organizations/{uuid}

Removes an organization with the provided uuid.

Example request

$ curl 'http://localhost:8080/admin-api/manage/v1/organizations/d2bc061d-867f-4075-a4bc-4d8c916fb923' -i -u '85d8884c-c1f2-4bd1-b46c-0f0af07ae77a:3YBA6sfr+ukblV/aipnXpg==' -X DELETE \
    -H 'Content-Type: application/json'

Example response

HTTP/1.1 204 No Content
X-Correlation-UUID: fc1f4ea8-e910-4f04-8a30-6bb6dbc2eff8

3.2. Api Key

An API to manage API Keys. Api Keys are used to authenticate on all Encap REST APIs. Through this API you can manage all API Keys, for all organizations, on the Encap Server.

3.2.1. The API key object

Field Type Description

Field	Type	Description
`api_key_id`	`UUID`	The API key ID, uuid, for the key.
`api_key_secret`	`String`	The API key secret. The secret is only part of the response when a API key is created, it is not returned when you fetch an API key
`description`	`String`	The description for the API key
`created_by`	`String`	The name/id of the creator of the API key
`created_on`	`String`	The date for when the API key was created. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'
`organization_id`	`UUID`	The ID of the organization the API key belongs to.
`generated_type`	`String`	Type defining how the key was created

api_key_id

UUID

The API key ID, uuid, for the key.

api_key_secret

String

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

description

String

The description for the API key

created_by

String

The name/id of the creator of the API key

created_on

String

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

organization_id

UUID

The ID of the organization the API key belongs to.

generated_type

String

Type defining how the key was created

Generated type values

Value Description

Value	Description
`WEB`	Created with the Admin Web UI.
`COMMAND_LINE`	Created with the command line scripts.
`ENCAP_SERVER`	Created implicitly by an action on the Encap Server.
`MIGRATION_JOB`	Created by the DB upgrade scripts.
`REST_API`	Created with the REST API.

WEB

Created with the Admin Web UI.

COMMAND_LINE

Created with the command line scripts.

ENCAP_SERVER

Created implicitly by an action on the Encap Server.

MIGRATION_JOB

Created by the DB upgrade scripts.

REST_API

Created with the REST API.

3.2.2. Create API Key

POST /admin-api/manage/v1/api-keys

Creates a new API key. The new key will either belong to the ADMIN organization that is making the request, or to the organization that is specified in the request body.

Arguments

Path Type Required Description

Path	Type	Required	Description
`description`	`String`	No	The description for the API key
`organization_id`	`UUID`	No	The id of the organization you want to create an API key for. If not provided the new API key will be created for the ADMIN organization authenticated for the request.

description

String

The description for the API key

organization_id

UUID

The id of the organization you want to create an API key for. If not provided the new API key will be created for the ADMIN organization authenticated for the request.

Returns

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

Example request

$ curl 'http://localhost:8080/admin-api/manage/v1/api-keys' -i -u '85d8884c-c1f2-4bd1-b46c-0f0af07ae77a:3YBA6sfr+ukblV/aipnXpg==' -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "description" : "Key for client A",
  "organization_id" : "c54babb9-d50e-4347-981c-6c31dc43e92c"
}'

Example response

HTTP/1.1 201 Created
X-Correlation-UUID: 696e1010-5478-4984-ab17-d6af13ce8838
Location: /manage/v1/api-keys/3a1e9bdf-19bc-47ee-b5b8-a0a0088431d6
Content-Type: application/json
Content-Length: 345

{
  "api_key_id" : "3a1e9bdf-19bc-47ee-b5b8-a0a0088431d6",
  "created_on" : "2025-03-17T16:58:03.028UTC",
  "created_by" : "85d8884c-c1f2-4bd1-b46c-0f0af07ae77a",
  "description" : "Key for client A",
  "generated_type" : "REST_API",
  "api_key_secret" : "0v1XPRdtQAGTbP0JTxh3lg==",
  "organization_id" : "c54babb9-d50e-4347-981c-6c31dc43e92c"
}

3.2.3. Get API key details

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

Get details for an API key.

Returns

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

Example request

$ curl 'http://localhost:8080/admin-api/manage/v1/api-keys/3a1e9bdf-19bc-47ee-b5b8-a0a0088431d6' -i -u '85d8884c-c1f2-4bd1-b46c-0f0af07ae77a:3YBA6sfr+ukblV/aipnXpg==' -X GET

Example response

HTTP/1.1 200 OK
X-Correlation-UUID: 182dff60-af9c-410a-9841-76c9428a4bff
Content-Type: application/json
Content-Length: 296

{
  "api_key_id" : "3a1e9bdf-19bc-47ee-b5b8-a0a0088431d6",
  "created_on" : "2025-03-17T16:58:03.547UTC",
  "created_by" : "85d8884c-c1f2-4bd1-b46c-0f0af07ae77a",
  "description" : "Key for client A",
  "generated_type" : "REST_API",
  "organization_id" : "c54babb9-d50e-4347-981c-6c31dc43e92c"
}

3.2.4. Get all API keys

GET /admin-api/manage/v1/api-keys

Returns a pagination object with a list of API key objects that belongs to the specified organization.

Request parameters

In addition to the pagination request parameters this API also has

Parameter Description

Parameter	Description
`organization_id`	The id of the organization you want to fetch all API keys for. If not provided it will fetch the API keys for the ADMIN organization.

organization_id

The id of the organization you want to fetch all API keys for. If not provided it will fetch the API keys for the ADMIN organization.

Example request

$ curl 'http://localhost:8080/admin-api/manage/v1/api-keys/?limit=3&offset=a95a8dac-09a4-477b-b801-6eae8d1cd9ad&organization_id=c54babb9-d50e-4347-981c-6c31dc43e92c' -i -u '85d8884c-c1f2-4bd1-b46c-0f0af07ae77a:3YBA6sfr+ukblV/aipnXpg==' -X GET

Example response

HTTP/1.1 200 OK
X-Correlation-UUID: 45aa54df-b2e7-4e13-93fd-a8e3cd5d150d
Content-Type: application/json
Content-Length: 1304

{
  "previous" : "/manage/v1/api-keys?limit=3&offset=f6992bee-d2e2-4b77-ba90-296e23f08ff8&organization_id=c54babb9-d50e-4347-981c-6c31dc43e92c",
  "next" : "/manage/v1/api-keys?limit=3&offset=bcec891d-e725-4146-ab77-a80e7e9acb3f&organization_id=c54babb9-d50e-4347-981c-6c31dc43e92c",
  "offset" : "a95a8dac-09a4-477b-b801-6eae8d1cd9ad",
  "limit" : 3,
  "items" : [ {
    "api_key_id" : "61d62e06-b5f9-4873-af5d-976f17576927",
    "created_on" : "2025-03-17T16:58:03.684UTC",
    "created_by" : "85d8884c-c1f2-4bd1-b46c-0f0af07ae77a",
    "description" : "Key for client A",
    "generated_type" : "REST_API",
    "organization_id" : "c54babb9-d50e-4347-981c-6c31dc43e92c"
  }, {
    "api_key_id" : "729a8479-8359-4825-8650-74b4793bb104",
    "created_on" : "2025-03-17T16:58:03.684UTC",
    "created_by" : "85d8884c-c1f2-4bd1-b46c-0f0af07ae77a",
    "description" : "Key for client A",
    "generated_type" : "REST_API",
    "organization_id" : "c54babb9-d50e-4347-981c-6c31dc43e92c"
  }, {
    "api_key_id" : "c0fe1b5f-df00-4ebb-bedf-36786c3be3a8",
    "created_on" : "2025-03-17T16:58:03.684UTC",
    "created_by" : "85d8884c-c1f2-4bd1-b46c-0f0af07ae77a",
    "description" : "Key for client A",
    "generated_type" : "REST_API",
    "organization_id" : "c54babb9-d50e-4347-981c-6c31dc43e92c"
  } ]
}

3.2.5. Delete API key

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

Deletes the API key with the specified id

Example request

$ curl 'http://localhost:8080/admin-api/manage/v1/api-keys/3a1e9bdf-19bc-47ee-b5b8-a0a0088431d6' -i -u '85d8884c-c1f2-4bd1-b46c-0f0af07ae77a:3YBA6sfr+ukblV/aipnXpg==' -X DELETE

Example response

HTTP/1.1 204 No Content
X-Correlation-UUID: d65db602-05ca-4cf3-b956-e806ead97a97

4. Statistics API

4.1. Database Cleanup Job

An API for extracting Database (DB) Cleanup job statistics.

4.1.1. The DB Cleanup job object

Field Type Description

Field	Type	Description
`id`	`UUID`	The id of the DB Cleanup job.
`status`	`String`	Status of the DB Cleanup job. May be STARTED, SUCCESS, FAILURE or VETOED.
`start_time`	`String`	Time for when the DB Cleanup job started. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'
`end_time`	`String`	Time for when the DB Cleanup job ended. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'
`completed_in`	`String`	Time it took for the DBCleanup job to complete. Returned in pattern HH:mm:ss
`cleanup_details`	`Array`	List of DB Cleanup Details, one object per table that was cleaned during the DB cleanup job.

id

UUID

The id of the DB Cleanup job.

status

String

Status of the DB Cleanup job. May be STARTED, SUCCESS, FAILURE or VETOED.

start_time

String

Time for when the DB Cleanup job started. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

end_time

String

Time for when the DB Cleanup job ended. Returned in pattern yyyy-MM-dd’T’HH:mm:ss.SSS’UTC'

completed_in

String

Time it took for the DBCleanup job to complete. Returned in pattern HH:mm:ss

cleanup_details

Array

List of DB Cleanup Details, one object per table that was cleaned during the DB cleanup job.

The DB Cleanup job details object

Field Type Description

Field	Type	Description
`details`	`String`	Details for the DB cleanup job.

details

String

Details for the DB cleanup job.

4.1.2. Get DB Cleanup job

GET /admin-api/statistics/v1/database-cleanup-jobs/{uuid}

Returns the DB Cleanup job object with the uuid.

Example request

$ curl 'http://localhost:8080/admin-api/statistics/v1/database-cleanup-jobs/c0a3f355-628c-40c0-b080-d23ed6906517' -i -u '85d8884c-c1f2-4bd1-b46c-0f0af07ae77a:3YBA6sfr+ukblV/aipnXpg==' -X GET

Example response

HTTP/1.1 200 OK
X-Correlation-UUID: b86a4d4a-7922-4864-b86d-6e1aa9b04d4d
Content-Type: application/json
Content-Length: 1823

{
  "id" : "c0a3f355-628c-40c0-b080-d23ed6906517",
  "status" : "SUCCESS",
  "start_time" : "2025-03-17T16:56:07.348UTC",
  "end_time" : "2025-03-17T16:58:07.348UTC",
  "completed_in" : "00:02:00",
  "cleanup_details" : [ {
    "details" : "Completed in 00:00:01. AuditThread completed in 00:00:00, and EncapThread completed in 00:00:01"
  }, {
    "details" : "\tAudit completed in 00:00:00, 8942 data sets updated/deleted, 16169.98 sets/sec, 99.8% of AuditThread; "
  }, {
    "details" : "\tSessionReferences completed in 00:00:00, 0 data sets updated/deleted, 0.00 sets/sec, 9.8% of EncapThread; "
  }, {
    "details" : "\tSession completed in 00:00:00, 1657 data sets updated/deleted, 2447.56 sets/sec, 55.6% of EncapThread; "
  }, {
    "details" : "\tAuthMethod completed in 00:00:00, 0 data sets updated/deleted, 0.00 sets/sec, 6.4% of EncapThread; "
  }, {
    "details" : "\tSessionContext completed in 00:00:00, 3114 data sets updated/deleted, 9000.00 sets/sec, 28.4% of EncapThread; "
  }, {
    "details" : "\tRegistration completed in 00:00:00, 0 data sets updated/deleted, 0.00 sets/sec, 12.8% of EncapThread; "
  }, {
    "details" : "\tScheduledJobEntries completed in 00:00:00, 0 data sets updated/deleted, 0.00 sets/sec, 6.3% of EncapThread; "
  }, {
    "details" : "\tDeviceData completed in 00:00:00, 201 data sets updated/deleted, 1233.13 sets/sec, 13.4% of EncapThread; "
  }, {
    "details" : "\tSafetyNetAttestations completed in 00:00:00, 0 data sets updated/deleted, 0.00 sets/sec, 6.2% of EncapThread; "
  }, {
    "details" : "\tIntermediatePushAttestations completed in 00:00:00, 0 data sets updated/deleted, 0.00 sets/sec, 6.2% of EncapThread; "
  }, {
    "details" : "\tAuthorizationTokens completed in 00:00:00, 0 data sets updated/deleted, 0.00 sets/sec, 6.2% of EncapThread; "
  } ]
}

4.1.3. Get all DB Cleanup jobs

GET /admin-api/statistics/v1/database-cleanup-jobs?limit=4&offset=9f847916-66fd-11eb-925a-331db2681953

Returns a pagination object with a list of DB Cleanup job objects excluding the cleanup_details. To see cleanup_details use the Get DB Cleanup job API described above.

Example request

$ curl 'http://localhost:8080/admin-api/statistics/v1/database-cleanup-jobs/?limit=4&offset=256a9a5f-56e0-44d4-9ca7-4a1bec2f0bd7' -i -u '85d8884c-c1f2-4bd1-b46c-0f0af07ae77a:3YBA6sfr+ukblV/aipnXpg==' -X GET

Example response

HTTP/1.1 200 OK
X-Correlation-UUID: a4f11583-00d4-4dcb-9f1e-c626392514c5
Content-Type: application/json
Content-Length: 1260

{
  "previous" : "/statistics/v1/database-cleanup-jobs?limit=4&offset=e78f0cae-11c5-4595-8172-ec63764ed9ec",
  "next" : "/statistics/v1/database-cleanup-jobs?limit=4&offset=592267b3-1cb8-4790-8801-f28ec698178e",
  "offset" : "256a9a5f-56e0-44d4-9ca7-4a1bec2f0bd7",
  "limit" : 4,
  "items" : [ {
    "id" : "acbea6a7-f697-4c6a-9011-f924f9815eba",
    "status" : "SUCCESS",
    "start_time" : "2025-03-17T16:56:07.759UTC",
    "end_time" : "2025-03-17T16:58:07.759UTC",
    "completed_in" : "00:02:00",
    "cleanup_details" : [ ]
  }, {
    "id" : "2943168d-8d1c-4167-a739-5e27d5fea81a",
    "status" : "SUCCESS",
    "start_time" : "2025-03-17T16:56:07.759UTC",
    "end_time" : "2025-03-17T16:58:07.759UTC",
    "completed_in" : "00:02:00",
    "cleanup_details" : [ ]
  }, {
    "id" : "ea23c6f9-e30d-43c7-a35f-a39afa957d29",
    "status" : "SUCCESS",
    "start_time" : "2025-03-17T16:56:07.759UTC",
    "end_time" : "2025-03-17T16:58:07.759UTC",
    "completed_in" : "00:02:00",
    "cleanup_details" : [ ]
  }, {
    "id" : "118088f6-3bdb-40b6-8307-6d2e84cef94e",
    "status" : "SUCCESS",
    "start_time" : "2025-03-17T16:56:07.759UTC",
    "end_time" : "2025-03-17T16:58:07.759UTC",
    "completed_in" : "00:02:00",
    "cleanup_details" : [ ]
  } ]
}

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

5.1. Response objects types

5.1.1. Overall status object

Field Type Description

Field	Type	Description
`status_all`	`String`	Overall queue health status
`queues`	`Array`	List of event callback queues

status_all

String

Overall queue health status

queues

Array

List of event callback queues

5.1.2. Queue details status object

Field Type Description

Field	Type	Description
`id`	`String`	App-config id for the event callback queue
`size`	`Number`	Number of items in events callback queue
`status`	`String`	Health status of the queue
`error`	`String`	If 'status' is FAILURE, the error field should contain details about the failure

id

String

App-config id for the event callback queue

size

Number

Number of items in events callback queue

status

String

Health status of the queue

error

String

If 'status' is FAILURE, the error field should contain details about the failure

5.1.3. Event-callback queue status

Status Description

Status	Description
`OK`	Queue health status is OK
`FAILURE`	Queue status is unhealthy. An unreachable callback endpoint or a full callback queue will cause this error.

OK

Queue health status is OK

FAILURE

Queue status is unhealthy. An unreachable callback endpoint or a full callback queue will cause this error.

5.2. Get API status

GET /api/admin/v1/status/callback

5.2.1. Example request

$ curl 'http://localhost:8080/api/admin/v1/status/callback' -i -u '85d8884c-c1f2-4bd1-b46c-0f0af07ae77a:3YBA6sfr+ukblV/aipnXpg==' -X GET

5.2.2. Example response - Status OK

HTTP/1.1 200 OK
X-Correlation-UUID: c64074ff-f2d4-4754-9f35-a8c4e5615a75
Content-Type: application/json
Content-Length: 137

{
  "queues" : [ {
    "id" : "cee947b1-eee3-42e5-9618-fab80be8928a",
    "size" : 10,
    "status" : "OK"
  } ],
  "status_all" : "OK"
}

5.2.3. Example response - Status FAILURE

HTTP/1.1 200 OK
X-Correlation-UUID: d8428ebb-2f03-467d-88c6-047fa3d762b3
Content-Type: application/json
Content-Length: 259

{
  "queues" : [ {
    "id" : "18755a96-2775-4287-b070-3819b4b592f4",
    "size" : 10000,
    "status" : "FAILURE",
    "error" : "Queue size is larger than limit (5000) for app-config: 18755a96-2775-4287-b070-3819b4b592f4"
  } ],
  "status_all" : "FAILURE"
}