Every ZofToken server has two different communication channels:
- A low traffic, custom designed binary protocol for the apps (ZofToken Universal App or any other that implements ZofToken SDK)
to handle token operations.
- A more standard, REST-like API for integrating any kind of existing system with the solution.
While the binary protocol is not secret and is in fact available as part of the SDK that allows other apps or components to 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 of ZofToken Server or ZaaS.
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: 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.
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 Server installations, it is still recommended to register for a free ZaaS subscription as this
provides an instant sandbox for experimenting and testing.
The available formats for the API are:
This is the raw description file as per the OpenAPI standard version 3.0 available in YAML and JSON formats.
This is the same OpenAPI file converted to a human-readable reference using the RapiPDF converter.
A standalone instance of Swagger UI serving the API description in a user-friendly interface to explore the API and parameters.
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.
- Install the ZofToken Universal App for your desired platform.
- Install the Insomnia client.
- Register for a free ZaaS subscription (for the sake of this example, the subscription is called “apitest”).
- In the ZaaS interface, create a service in your subscription (for the sake of this example, the service is called “testservice”).
- In the ZaaS interface, create a user in that service (for the sake of this example, the user is called “testuser”).
- Enroll the user in your ZofToken App.
- Import the API workspace into Insomnia.
- Click on the environment option and select “ZofToken”.
- 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).
- 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.