This is the API documentation for the BitMaelum key resolver service. It contains all operations, input and output for communicating with the key resolver service.
This API is useful when creating your own BitMaelum client or tooling that needs to read or write addresses, organisations or routing information.
All read operations (GET requests) can be done unauthenticated. Some write operations are only allowed when
authenticated. For instance, when updating or deleting existing objects. Creating new objects can be added
without authentication.
Authentication is done through sending a Authentication header field in the HTTP request. THis field consists
of the following:
Authentication: BEARER <token>The token depends on the kind of object:
Address authentication
sha256(hash of the address + routing ID of the address + serial number of the address)All these fields can be retrieved by issuing a GET request on the address hash. These fields must be concatted together
(in the correct order), and run through the SHA256 hash function.
The result of the hash function must be signed with the PRIVATE KEY of the address. The resulting signature must be
base64 encoded and this will be the bearer token.
Note that the retrieval of fields, and the actual post are two seperate requests and are thus not atomic. It might be possible that another request in between already updated the object. In that case, the serial number of the object will have changed, and the token for your request will be invalid.
Organisation authentication
Organisation authentication is needed for changing organisation data or (soft) deleting the organisation.
It works in the same way as address authentication, except it uses the following sha256 hash to be signed:
sha256(hash of the organisation + serial number of the organisation)Routing authentication
Routing authentication is needed for changing routing data for a given mail server.
It works in the same way as address or organisation authentication, except it uses the following sha256 hash to be signed:
sha256(hash of the routing + serial number of the routing)In order to create a new organisation or address, you need to do proof-of-work. This proof will be checked when
creating the organisation or address in the key resolver. The difficulty level of the proof-of-work depends on the key
resolver and will gradually increase over time. To find the current difficulty level, you can get the config.json
file of the key resolver by a GET /config.json (see below).
Retrieves information about an address object
path Parameters
| hash required | string Example: 2244643da7475120bf84d744435d15ea297c36ca165ea0baaa69ec818d0e952f hash of the address object to query |
Responses
Response samples
- 200
- 400
- 404
{- "hash": "2244643da7475120bf84d744435d15ea297c36ca165ea0baaa69ec818d0e952f",
- "public_key": "rsa MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvzbZbLUcFRy8fii8zZ7KI8X6cUxjD/Duf4wSqi+jMCcxPuZU1/YX8QhDNyVnnutOz/bJJTSLiJt4zuphCDqjf6lhR+wCrB1hZxqwiNbMHM0cdvaScgMj6lS8xboheZ5n39+jtfjdigIxz7DUtGFzzLeGzj3ENRrPEwkmYooCAh3s0PdrHeN461jNrMOJArqd4vJ0VyCr9Vd6fPSN0OoW6ju7NeqynDBbs4iKHcCyDPXrlWY6e3ihCJ6ksw8dNbbA+RlsHHBU7pOk7Myk0T3wTK+/FcmUbjHxaDKJcP0Cao/Hrog3wAYshnGnjdVkK+YfXgeo7o2TU1apzqLJsORTyQIDAQAB",
- "proof": "27$MmU0NTUxZGU4MDRlMjdhYWNmMjBmOWRmNWJlM2U4Y2QzODRlZDY0NDg4YjIxYWIwNzlmYjU4ZThjOTAwNjhhYg==$180774681",
- "serial_number": 1609964031705632800,
- "routing_id": "323250728593e92f50bf1572d10318912fd611dd0f4e5d36726c0c0757b29e03",
- "redirect_hash": "string"
}Returns an organisation object
This endpoint will return an organisation object based on its hash. Deactivated organisations cannot be found. There is no difference in return values wheter an object is deactivated or simply does not exist.
path Parameters
| hash required | string hash of the organisation object to query |
Responses
Response samples
- 200
- 404
{- "hash": "323250728593e92f50bf1572d10318912fd611dd0f4e5d36726c0c0757b29e03",
- "public_key": "ed25519 MCowBQYDK2VwAyEAvGQhl5wUx3F2RunI3dU74atL3kbBTvJg+QkrErEUivk=",
- "proof": "27$MmU0NTUxZGU4MDRlMjdhYWNmMjBmOWRmNWJlM2U4Y2QzODRlZDY0NDg4YjIxYWIwNzlmYjU4ZThjOTAwNjhhYg==$180774681",
- "serial_number": 1607509742876620000
}Create or update an organisation object
This call either creates an organisation object, or updates an existing one. When creating an object, no authentication is needed. When updating an existing object, an authentication token must be present.
path Parameters
| hash required | string hash of the organisation object to query |
Responses
Purges an organisation object
This call will purge an organisation object from the key resolver. It cannot be undone. Once purged, the organisation is considered available for other users to claim. An organisation object can only be deleted once it has been deactivated. Active organisation objects cannot be purged.
path Parameters
| hash required | string hash of the organisation object to query |
Responses
Response samples
- 200
- 401
- 404
- 500
{- "status": "ok",
- "message": "organisation deleted"
}Soft delete an organisation object
An organisation object can be soft-deleted. This will deactivate the organisation and will not found when querying the object's hash. It will automatically be purged from the system after a (unspecified) number of days. An object can be restored through an undelete request until it's purged. Until that time, the object cannot be taken over by other users.
path Parameters
| hash required | string hash of the organisation to query |
Responses
Queries a routing object by ID
path Parameters
| hash required | string Example: 323250728593e92f50bf1572d10318912fd611dd0f4e5d36726c0c0757b29e03 routing object to query |
Responses
Response samples
- 200
- 404
{- "hash": "323250728593e92f50bf1572d10318912fd611dd0f4e5d36726c0c0757b29e03",
- "public_key": "ed25519 MCowBQYDK2VwAyEAvGQhl5wUx3F2RunI3dU74atL3kbBTvJg+QkrErEUivk=",
- "routing": "bitmaelum.noxlogic.nl",
- "serial_number": 1607509742876620000
}Creates or updates a routing object
path Parameters
| hash required | string Example: 323250728593e92f50bf1572d10318912fd611dd0f4e5d36726c0c0757b29e03 routing object to query |
Request Body schema: application/json
Routing object
| public_key required | string New public key for this routing object |
| routing required | string New routing URL or IP for this routing object |
Responses
Request samples
- Payload
{- "public_key": "ed25519 MCowBQYDK2VwAyEAvGQhl5wUx3F2RunI3dU74atL3kbBTvJg+QkrErEUivk=",
- "routing": "bitmaelum.noxlogic.nl"
}Response samples
- 200
- 400
- 401
- 500
{- "status": "ok",
- "message": "string"
}Retrieves the key resolver configuration settings.
The key resolver configuration dictates how certain inputs should adhere to. For now, this means that it will return the minimum number of bits for proof-of-work that needs to be done before accepting an address or organisation.
Responses
Response samples
- 200
{- "value": {
- "proof_of_work": {
- "address": 27,
- "organisation": 29
}
}
}