Unique Tokens API

The Unique Tokens API of Unique Tokens GmbH is a RESTful interface for generating any number of randomized serial numbers (also called tokens) for many parallel production lines. The tokens can consist of any number of digits from any preset or, if required, a completely user-customizable ASCII or Unicode (also mixed) alphabet. It supports secure and protected machine-to-machine access via HTTP over TLS to the commercial and paid, cloud-based and highly efficient microservice Unique Tokens Core.

The Unique Tokens API uses the popular payment processor Stripe to validate the payment status immediately before triggering a specific production job on the Service. To do this, each production request must contain valid payment confirmation data. Stripe payment processing requires certain steps on the client side to meet this requirement. Our Android application UT Cockpit, soon to be available on the Google Play Store, guides the user through all the necessary steps to get tokens from our API, including integrated payment, in a simple and user-friendly way.

Each core instance generates unique, binary raw data sequences with the optimal bit width (any continuous, also beyond 2³² or 2⁶⁴) for the requested token type, size and length, converts them all into tokens and makes them available for download. The stream of binary raw data and thus also the tokens of each production line form a new sequence with perfect randomness that follows the logical rules of a high-dimensional cellular automaton that is randomly initialized differently each time. Therefore, every token sequence is neither reproducible nor predictable and there are no identical or similar token sequences, neither in whole nor in part. This highly optimized algorithmic construction principle knows no number or character limits and guarantees that every token is generated exactly once at a certain point in time with linear time complexity and without having to keep all tokens produced up to that point.

After a certain number of tokens have been produced by the remote service and downloaded by the service consumer, the current status of a production line that is able to continue running can be captured via the API, saved by the responsible customer as a small snapshot in a safe place and later restored via the API in order to continue the production line. These capturing and restoring processes take place free of charge and reliably, in particular without accidentally mixing up different production lines, duplicating tokens that have already been produced in a specific production line, or discarding tokens pending in it, if the restored production line continues.

Every Unique Tokens Core instance acts as a short-living, not multi-tenant microservice. Each HTTP request is authenticated by a distinct Session-Key, and per core instance all of them are authorized by the same Api-Key. The usage of more than one service consumer session per core instance in parallel is possible, but NOT RECOMMENDED. Multiple production lines per service consumer session in parallel are possible and RECOMMENDED.

The Unique Tokens API strictly follows the JSON:API specification. As a result, the structure of the content of the data sent up from the service consumer to the remote service as JSON largely corresponds to the structure of the content that is sent back from the remote service to the service consumer as JSON. This principle is consistently adhered to, also at the cost of a certain overhead in terms of transmitted data, in particular whenever lists of several objects of the same type are sent back.

Step-by-step guides

These step-by-step guides provide a hands-on learning path for common business cases to create randomized serial numbers using the Unique Tokens API. The guides build upon each other and range from a minimal working example to full-fledged examples, including user-customizable alphabets for long-term available production lines to accommodate specific business cases.

If a description of a JSON request or JSON response refers to a single attribute-value pair or to a path thereof, the attribute path is flattened and all of it is printed in italics in the description for better readability. For example, the JSON path {"data": {"attributes": {"note": "A note"}}} would appear in the description as data attributes note: A note.

Some values in the descriptions of the HTTP request headers, JSON requests and JSON responses have been replaced by uniform placeholders for safety reasons: KKKKKKKK-KKKK-KKKK-KKKK-KKKKKKKKKKKK represents an Api-Key, SSSSSSSS-SSSS-SSSS-SSSS-SSSSSSSSSSSS a Session-Key, HHHHHHHH-HHHH-HHHH-HHHH-HHHHHHHHHHHH a meta seed, and XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX a data id that would appear at this place if the API was used for real.

In order to be able to test every distinct step as a one-shot Linux CLI command, the HTTP method of the described endpoint, its HTTP request headers and its JSON request are also shown as a HTTPie command line example. Before running the example, the SERVER:PORT placeholder MUST be replaced by the real address and all other placeholders MUST be replaced by the corresponding values too. The example lines MUST be executed altogether as a singular console command.

Beginner's intro

The beginner's intro leads to a minimal working example with a preset alphabet:

1. Firstly, a new, protected service consumer session is established.
2. Next, for the character set ⚀⚁⚂⚃⚄⚅ of the preset Unicode alphabet DICE, the number of tokens that can be generated with 5 digits is requested.
3. Building on this, a production line is requested and starts immediately for all of the 7,776 available tokens.
4. After the token production is finished, the CSV-formatted tokens data are requested and saved locally as a CSV file.
5. Finally, the production line, which has been completely emptied and has served its purpose, is dismantled and the service consumer session is closed.

Trainee's skills

The trainee's skills allows to learn a more feature-rich example with a preset alphabet:

1. Firstly, a new, protected service consumer session is established.
2. Next, perhaps due to existing business case requirements, a list of preset alphabets is requested that have a character set with a length of 16 characters. The character set 0123456789ABCDEF is found in it as UPPER_HEX preset ASCII alphabet and a decision is made to use it.
3. Building on this, a production line is requested and starts immediately for a number of 1,000 tokens as only a small part of 1,099,511,627,776 tokens, that can be generated with 10 digits.
4. After the token production is finished, the CSV-formatted and GZ-compressed data are requested and saved locally as a GZ file.
5. In addition, the expected file size of the CSV-formatted and GZ-compressed data can be requested prior to downloading.
6. Finally, the production line, which has not been completely emptied but has served its purpose, is dismantled and the service consumer session is closed.

Expert's leaflet

The expert's leaflet presents an almost complete example with a preset alphabet:

1. Firstly, a new, protected service consumer session is established.
2. Next, perhaps to learn about other alphabets, a list of all preset alphabets is requested. The character set abcdefghijklmnopqrstuvwxyz is found in it as LOWER_LATIN alphabet and a decision is made to use it.
3. Then, the number of tokens that can be generated with 3 digits is requested, which is responded as a number of 17,576. It is decided to retrieve this available amount in two temporally separated parts.
4. Building on this, a production line is requested and starts immediately for a number of 8,788, which represents the 1st tokens part.
5. Then, a confirmation is requested, that the production of the 1st tokens part has been finished. The tokens data and the snapshot of the production line, both linked in it, are available for download.
6. After the token production is finished, the CSV-formatted tokens data of the 1st tokens part is requested and saved locally as a CSV file.
7. In addition, the expected file size of the CSV-formatted tokens data of the 1st tokens part can be requested prior to downloading.
8. To capture the production line after the 1st tokens part, the snapshot of the production line is requested and saved locally as a BLOB file.
9. In addition, the expected file size of the snapshot of the production line can be requested prior to downloading.
10. Then, the production line, which has not been completely emptied but has served its purpose for the 1st tokens part, is dismantled.
11. Meanwhile, for short time testing purposes, the service consumer session can remain open, but for real use cases it is RECOMMENDED to close it now and establish a new service consumer session later with the same Api-Key as used before.
12. After that, using the snapshot previously saved locally as a BLOB file, the same production line as before is requested and starts immediately for a number of 8,788, which represents the 2nd half of the available tokens.
13. Then, a confirmation is requested, that the production of the 2nd tokens part has been finished. The tokens data, linked in it, are available for download. A snapshot of the completely emptied production line is not available here.
14. After the token production is finished, the CSV-formatted tokens data of the 2nd tokens part is requested and saved locally as a CSV file.
15. In addition, the expected file size of the CSV-formatted tokens data of the 2nd tokens part can be requested prior to downloading.
16. Finally, the production line, which has been completely emptied and now has served its purpose for the 2nd tokens part too, is dismantled and the service consumer session is closed.

Veteran's trail

The veteran's trail leads to a full-fledged example with a preset alphabet:

1. Firstly, a new, protected service consumer session is established.
2. Then, a confirmation is requested, that the service consumer session has been established. The remote service also returns some known data about the customer for which the current Api-Key was assigned.
3. Next, willing to fulfill the European Pack Coding Guidelines, a list of all preset ASCII alphabets is requested. The character set 0123456789ABCDEFGHKMNPRSTVWXYZ is found in it as UPPER_EPCG30 alphabet and a decision is made to use it.
4. Then, the number of tokens that can be generated with 20 digits is requested, which is responded as 348,678,440,100,000,000,000,000,000,000, which represents a big integer number with 99 bits. It is decided to retrieve two temporally separated parts of 50,000 tokens each for now with the option of being able to continue the production line at any later time if necessary.
5. Building on this, a production line is requested and starts immediately for a number of 50,000, which represents the 1st tokens part.
6. While the production is on the way, a just-in-time information can be requested, whether the production of the 1st tokens part has been requested, started or ended. The tokens data and the snapshot are not available at this points of time.
7. Then, a confirmation is requested, that the production of the 1st tokens part has been finished. The tokens data and the snapshot of the production line, both linked in it, are available for download.
8. After the production of the 1st tokens part has been finished, the CSV-formatted and GZ-compressed data are requested and saved locally as a GZ file.
9. In addition, the expected file size of the CSV-formatted and GZ-compressed data can be requested prior to downloading.
10. To capture the production line after the 1st tokens part, the snapshot of the production line is requested and saved locally as a BLOB file.
11. In addition, the expected file size of the snapshot of the production line can be requested prior to downloading.
12. Then, the production line, which has not been completely emptied but has served its purpose for the 1st tokens part, is dismantled.
13. Meanwhile, for short time testing purposes, the service consumer session can remain open, but for real use cases it is RECOMMENDED to close it now and establish a new service consumer session later with the same Api-Key as used before.
14. After that, using the snapshot previously saved locally as a BLOB file, the same production line as before is requested and starts immediately for a number of 50,000, which represents the 2nd tokens part.
15. While the production is on the way, a just-in-time information can be requested, whether the production of the 2nd tokens part has been requested, started or ended. The tokens data and the snapshot are not available at this points of time.
16. Then, a confirmation is requested, that the production of the 2nd tokens part has been finished. The tokens data and the snapshot of the production line, both linked in it, are available for download.
17. After the production of the 2nd tokens part has been finished, the CSV-formatted and GZ-compressed data are requested and saved locally as a GZ file.
18. In addition, the expected file size of the CSV-formatted and GZ-compressed data can be requested prior to downloading.
19. To capture the production line after the 2nd tokens part, the snapshot of the production line is requested and saved locally as a BLOB file.
20. In addition, the expected file size of the snapshot of the production line can be requested prior to downloading.
21. Finally, the production line, which has not been completely emptied but has served its purpose for the 2nd tokens part too, is dismantled and the service consumer session is closed.
22. Since the production line was saved as a snapshot even after the 2nd (and for the time being last) tokens part was finished, the production line can continue again and again at any later time as long as it is not completely empty and a current, corresponding snapshot is available to restore the production line.

Master's game

The master's game allows to replay a full-fledged example with a custom alphabet:

1. Firstly, a new, protected service consumer session is established.
2. Then, a confirmation is requested, that the service consumer session has been established. The remote service also returns some known data about the customer for which the current Api-Key was assigned.
3. Next, a list of preset alphabets containing the characters AEIOU is requested. It finds some preset ASCII alphabets that contain them among with many other characters.
4. However, due to existing business case requirements, an alphabet for tokens is required that only contains these five capital vowels and therefore a custom alphabet is requested.
5. Next, confirmation of the availability of the custom alphabet by identifier is requested.
6. In addition, confirmation of the availability of custom alphabets, filtered according to a length of five characters, is requested.
7. Then, the number of tokens that can be generated with 100 digits is requested, which is responded as 7,888,609,052,210,118,054,117,285,652,827,862,296,732,064,351,090,230,047,702,789,306,640,625, which represents a big integer number with 233 bits. It is decided to retrieve two temporally separated parts of 1,000 tokens each for now with the option of being able to continue the production line at any later time if necessary.
8. Building on this, a production line is requested and starts immediately for a number of 1,000, which represents the 1st tokens part.
9. While the production is on the way, a just-in-time information can be requested, whether the production of the 1st tokens part has been requested, started or ended. The tokens data and the snapshot are not available at this points of time.
10. Then, a confirmation is requested, that the production of the 1st tokens part has been finished. The tokens data and the snapshot of the production line, both linked in it, are available for download.
11. After the production of the 1st tokens part has been finished, the CSV-formatted and GZ-compressed data are requested and saved locally as a GZ file.
12. In addition, the expected file size of the CSV-formatted and GZ-compressed data can be requested prior to downloading.
13. To capture the production line after the 1st tokens part, the snapshot of the production line is requested and saved locally as a BLOB file.
14. In addition, the expected file size of the snapshot of the production line can be requested prior to downloading.
15. Then, the production line, which has not been completely emptied but has served its purpose for the 1st tokens part, is dismantled.
16. Meanwhile, for short time testing purposes, the service consumer session can remain open, but for real use cases it is RECOMMENDED to close it now and establish a new service consumer session later with the same Api-Key as used before.
17. After that, using the snapshot previously saved locally as a BLOB file, the same production line as before is requested and starts immediately for a number of 1,000, which represents the 2nd tokens part.
18. While the production is on the way, a just-in-time information can be requested, whether the production of the 2nd tokens part has been requested, started or ended. The tokens data and the snapshot are not available at this points of time.
19. Then, a confirmation is requested, that the production of the 2nd tokens part has been finished. The tokens data and the snapshot of the production line, both linked in it, are available for download.
20. After the production of the 2nd tokens part has been finished, the CSV-formatted and GZ-compressed data are requested and saved locally as a GZ file.
21. In addition, the expected file size of the CSV-formatted and GZ-compressed data can be requested prior to downloading.
22. To capture the production line after the 2nd tokens part, the snapshot of the production line is requested and saved locally as a BLOB file.
23. In addition, the expected file size of the snapshot of the production line can be requested prior to downloading.
24. Next, the production line, which has not been completely emptied but has served its purpose for the 2nd tokens part too, is dismantled.
25. Finally, the custom alphabet, which has served its purpose for now, is deleted and the service consumer session is closed.
26. Since the production line was saved as a snapshot even after the 2nd (and for the time being last) tokens part was finished, the production line can continue again and again at any later time as long as it is not completely empty and a current, corresponding snapshot is available to restore the production line.

Admin's toolbox

The admin's toolbox shows intended operations for quickly cleaning up the current session:

1. Firstly, all tokens of the current session are requested. Then, all tokens of the current session are deleted. After that, for testing purposes the previous step is repeated.
2. Next, all custom alphabets of the current session are requested. Then, all custom alphabets of the current session are deleted. After that, for testing purposes the previous step is repeated.

Analyst's panel

The analyst's panel shows how to get an built-in stochastic analysis of generated tokens:

1. Firstly, a new, protected service consumer session is established.
2. Next, for the character set ⚀⚁⚂⚃⚄⚅ of the preset ASCII alphabet DICE, the number of tokens that can be generated with 5 digits is requested.
3. Building on this, a production line with integrated stochastic analysis at metrics level is requested and starts immediately for all of the 7,776 available tokens.
4. Then, a confirmation is requested, that the production of the tokens with integrated stochastic analysis at metrics level has been finished.
5. After the token production is finished, the CSV-formatted tokens data are requested and saved locally as a CSV file.
6. In addition, the expected file size of the CSV-formatted tokens data can be requested prior to downloading.
7. Next, the JSON-formatted stochastic analysis at metrics level is requested and saved locally as a JSON file.
8. In addition, the expected file size of the JSON-formatted stochastic analysis at metrics level can be requested prior to downloading.
9. Next, the CSV-formatted tokens data scores are requested and saved locally as a CSV file.
10. In addition, the expected file size of the CSV-formatted tokens data scores can be requested prior to downloading.
11. Next, the CSV-formatted tokens data deltas are requested and saved locally as a CSV file.
12. In addition, the expected file size of the CSV-formatted tokens data deltas can be requested prior to downloading.
13. Finally, the production line with integrated stochastic analysis at metrics level, which has been completely emptied and has served its purpose, is dismantled and the service consumer session is closed.

Hacker's space

The hacker's space shows a handful of tricky attempts to outsmart the API remote service:

1. Firstly, a service consumer session list without an Api-Key is attempted. Here the API remote service is attacked by trying to get all service consumer sessions with a random Api-Key.
2. Next, a session for an unknown customer is attempted. Here the API remote service is attacked by trying to sent a random Api-Key in the HTTP request headers.
3. Then, a session for a revoked customer is attempted. Here the API remote service is attacked by trying to sent a revoked Api-Key in the HTTP request headers.
4. Next, a new, protected service consumer session is established in order to be able to carry out further attacks based on this.
5. Then, a deleting of unknown tokens is attempted. Here the API remote service is attacked by trying to delete a production line with a random identifier.
6. Then, a posting of out of minimum tokens is attempted. Here the API remote service is attacked by trying to get a number of tokens less than the algorithm-related minimum in the HTTP request body.
7. Then, a posting of out of maximum tokens is attempted. Here the API remote service is attacked by trying to get a number of tokens more than the algorithm-related maximum in the HTTP request body.
8. Then, a posting of out of reachable tokens is attempted. Here the API remote service is attacked by trying to get a number of tokens more than the agreement-related maximum in the HTTP request body.
9. Finally, the service consumer session is closed.