Introduction

Every ZofToken server has two different communication channels:

• A low traffic, custom designed binary protocol over UDP for the ZofToken App to handle token operations.
• A more standard, REST-like API for integrating any kind of existing system with the solution.

While the UDP traffic is in no way secret and an SDK is available so that other apps or components can operate directly as tokens, this document is meant to describe the second API as this is the one the organization would need to use to integrate ZofToken into their systems, whether this is a private installation or ZaaS.

API design

In the introduction, the API is described as “REST-like” instead of simply REST because there have been a number of specific design decisions geared towards maximizing the simplicity of integration. From the start, we wanted the most basic operation needed for a system to integrate with ZofToken (checking the status of a token) to be a single HTTP GET request that could be equally simple to execute in the most cutting-edge development framework as it would be in a 15 year old legacy application.

With that in mind, the following is a list of these design decisions:

• The only two verbs used in the API are GET and POST which should be supported out of the box by any library, SDK or programming language that is able to handle HTTP connections. This is why you will see that deleting a token is a POST to a specific endpoint instead of a DELETE one to the same endpoint that handles enrollments.
• Every GET uses only query parameters, every POST uses a JSON body and all responses are JSON. These are standard in modern systems and can easily be built or parsed in legacy systems.
• Every call includes an authkey to validate proper authorization. While many modern APIs use standards like OAuth 2.0 for authorization, this adds an extra, and potentially significant, layer of complexity to the integration with legacy applications that ZofToken instead handles in a simpler way with user-defined authkeys.
• While each response carries a human-readable message, HTTP status codes in responses are set according to standard rules: 200 is success, 400 is a bad call (most likely invalid parameters), 403 is a security issue (most likely an invalid authkey), 404 is not found (most likely an invalid user or service name) and 500 is an internal error (most likely a database issue which can be retried if transient and in every case will be logged for debugging).
• This is more of a configuration issue than an API one but since it affects API calls, we mention it here: The ZofToken server can be configured to accept HTTPS calls (which naturally requires providing it with a certificate and matching private key) or to accept unencrypted HTTP calls (for example, if it is behind a secure reverse proxy). Regardless of the configuration decision, as authkeys travel with each request, it is strongly recommended that no unencrypted calls are ever made to the API, even on internal networks.

API description

The API is provided in several different formats so that each developer who is working on an integration can choose whatever fits their workflow and tooling best.

For private ZofToken installations, it is still recommended to register for a free ZaaS subscription as this provides an instant sandbox for experimenting and testing.

The formats available for the API are:

OpenAPI 3.0

• This is the raw description file as per the OpenAPI standard version 3.0 available in YAML and JSON formats.

PDF reference

• This is the same OpenAPI file converted to a human-readable reference using the RapiPDF converter.

Swagger UI

• A standalone instance of Swagger UI serving the API description in a user-friendly interface to explore the API and parameters.

Insomnia

• This is an exported workspace for the popular Insomnia REST Client which includes all API calls.

Basic usage example

This simple procedure, which shouldn’t take more than 10 minutes, will help you understand how the ZofToken solution works.

1. Install the ZofToken App for your appropiate platform.
2. Install the Insomnia client.
3. Register for a free ZaaS subscription (for the sake of this example, the subscription is called “apitest”).
4. In the ZaaS interface, create a service in your subscription (for the sake of this example, the service is called “testservice”).
5. In the ZaaS interface, create a user in that service (for the sake of this example, the user is called “testuser”).
6. Enroll the user in your ZofToken App.
7. Import the API workspace into Insomnia.
8. Click on the environment option and select “ZofToken”.
9. Click on “Manage Environments”, configure service_id (in this example, it would be “apitest_testservice”) and configure auth_string (copy the “Admin Auth” provided by ZaaS).
10. At this point you are all set to use the entire API from Insomnia, you can test the “Token Status” endpoint (changing user id to your user name, “testuser” in this example) which should show a 2 for closed if you enrolled your token correctly in step 6, and should later show a 1 after you open it.