Skip to main content

Audit Trail GW API Documentation

This is the API documentation for the Audit Trail Gateway of the Integration Services. For further information have a look at our Wiki.

Version: v0.1​

/channel-info/search​

GET​

Summary​

Search for a channel

Description​

Search for a channel. A client can search for a channel which it is interested in.

Parameters​
NameLocated inDescriptionRequiredSchema
author-idqueryNostring
namequeryNostring
topic-typequeryNostring
topic-sourcequeryNostring
createdqueryNodateTime
latest-messagequeryNodateTime
limitqueryNonumber
indexqueryNonumber
Responses​
CodeDescription
200Returns information about searched channels
401No valid api key provided / Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

/channel-info/channel/{channelAddress}​

GET​

Summary​

Get information about a channel

Description​

Get information about a channel with address channel-address.

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
Responses​
CodeDescription
200Returns information about the channel
401No valid api key provided
5XXUnexpected error

DELETE​

Summary​

Delete information of a channel

Description​

Delete information of a channel with address channel-address. The author of a channel can delete its entry in the database. In this case all subscriptions will be deleted and the channel won’t be found in the system anymore. The data & channel won’t be deleted from the IOTA Tangle since its data is immutable on the tangle!

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
Responses​
CodeDescription
200Channel successfully deleted
401No valid api key provided/ Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

/channel-info/channel​

POST​

Summary​

Add an existing channel into the database

Description​

Add an existing channel into the database. Clients are able to add existing channels into the database so others can subscribe to them. This will be automatically called when a channel will be created.

Responses​
CodeDescription
201Channel successfully added
401No valid api key provided/ Not authenticated
404Channel not found.
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

PUT​

Summary​

Update channel information

Description​

Update channel information. The author of a channel can update topics of a channel.

Responses​
CodeDescription
200Channel successfully added
401No valid api key provided/ Not authenticated
404Channel not found.
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

/channels/create​

POST​

Summary​

Create a new channel

Description​

Create a new channel. An author can create a new channel with specific topics where other clients can subscribe to.

Responses​
CodeDescription
201Returns the created channel
401No valid api key provided / Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

/channels/logs/{channelAddress}​

POST​

Summary​

Write data to a channel

Description​

Write data to a channel with address channel address. Write permission is mandatory. The type and metadata fields are not encrypted to have a possibility to search for events. The payload is stored encrypted for encrypted channels.

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
Responses​
CodeDescription
200Returns a link to the written data
401No valid api key provided / Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

GET​

Summary​

Get data from the channel

Description​

Get data from the channel with address channel address. The first possible message a subscriber can receive is the time the subscription got approved all messages before are not received. Read permission is mandatory.

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
limitqueryNonumber
indexqueryNonumber
ascqueryNoboolean
start-datequeryNodateTime
end-datequeryNodateTime
Responses​
CodeDescription
200Returns data from the channel
401No valid api key provided / Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

/channels/history/{channelAddress}​

GET​

Summary​

Get the history of a channel.

Description​

Get all data of a channel using a shared key (in case of encrypted channels). Mainly used from auditors to evaluate a log stream.

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
preshared-keyqueryPreshared key defined by the author to encrypt/decrypt data.Yesstring
Responses​
CodeDescription
200Received history.
5XXUnexpected error

/channels/validate/{channelAddress}​

POST​

Summary​

Validates channel data by comparing the log of each link with the data on the tangle.

Description​

Validates data of a channel.

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
Responses​
CodeDescription
200Returns validated result.
401No valid api key provided / Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

/channels/re-import/{channelAddress}​

POST​

Summary​

Re import the data from the tangle into the database.

Description​

The user can decide to re-import the data from the Tangle into the database. A reason for it could be a malicious state of the data.

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
Responses​
CodeDescription
200Reimport successful.
401No valid api key provided / Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

/info​

GET​

Summary​

Get information about the server

Description​

Get information about the server like commitHash, server identity id and api version

Responses​
CodeDescription
200Returns information about the server
5XXUnexpected error

/subscriptions/{channelAddress}​

GET​

Summary​

Get all subscriptions of a channel.

Description​

Get all subscriptions of a channel. Use the is-authorized query parameter to filter for authorized subscriptions.

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
is-authorizedqueryNoboolean
Responses​
CodeDescription
200Subscriptions
401No valid api key provided/ Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

/subscriptions/{channelAddress}/{id}​

GET​

Summary​

Get a subscription by identity id.

Description​

Get a subscription of a channel by identity id.

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
idpathYesstring
Responses​
CodeDescription
200Subscriptions
401No valid api key provided/ Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

POST​

Summary​

Adds an existing subscription

Description​

Adds an existing subscription (e.g. the subscription was not created with the api but locally.)

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
idpathYesstring
Responses​
CodeDescription
201Subscription added
400Subscription already added or params missing
401No valid api key provided/ Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

PUT​

Summary​

Updates an existing subscription

Description​

Updates an existing subscription

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
idpathYesstring
Responses​
CodeDescription
200Subscription updated
400Missing channelAddress / id
401No valid api key provided/ Not authenticated
404No subscription found
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

DELETE​

Summary​

Deletes subscription

Description​

Deletes an existing subscription

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
idpathYesstring
Responses​
CodeDescription
200Subscription deleted
400Missing channelAddress / id
401No valid api key provided/ Not authenticated
404No subscription found
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

/subscriptions/request/{channelAddress}​

POST​

Summary​

Request subscription to a channel

Description​

Request subscription to a channel with address channel-address. A client can request a subscription to a channel which it then is able to read/write from.

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
Responses​
CodeDescription
201Link to requested subscription
400Subscription already requested
401No valid api key provided/ Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

/subscriptions/authorize/{channelAddress}​

POST​

Summary​

Authorize a subscription to a channel

Description​

Authorize a subscription to a channel with address channel-address. The author of a channel can authorize a subscriber to read/write from a channel. Eventually after verifying its identity (using the SSI Bridge).

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
Responses​
CodeDescription
200Link to requested subscription
401No valid api key provided/ Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

/subscriptions/revoke/{channelAddress}​

POST​

Summary​

Revoke subscription to a channel.

Description​

Revoke subscription to a channel. Only the author of a channel can revoke a subscription from a channel.

Parameters​
NameLocated inDescriptionRequiredSchema
channelAddresspathYesstring
Responses​
CodeDescription
200Sucessfully revoked the subscription.
401No valid api key provided/ Not authenticated
5XXUnexpected error
Security​
Security SchemaScopes
BearerAuth
ApiKey

Models​

CreateChannelBodySchema​

NameTypeDescriptionRequired
namestringA channel can be searched by its name.Yes
descriptionstringAn optional description for a channel.No
subscriptionPasswordstringIf a subscriptionPassword is set, all data is encrypted with the password. It need to be made sure, the subscription password is sent when interacting with the APIs of the channel-service and subscription-service.No
topics[ object ]Yes
hasPresharedKeybooleanIf the channel has a preshared key (hasPresharedKey=true) but non is set in the presharedKey property it will be generated by the api.No
seedstringIf left empty the api will generate a seed automatically. Always store your seed otherwise the data can not be reimported.No
presharedKeystringIf the channel has a preshared key (hasPresharedKey=true) but non is defined here the presharedKey will be generated by the api.No

AddChannelLogBodySchema​

NameTypeDescriptionRequired
typestringPublic available type.No
createddateTimePublic available date.No
metadataPublic available metadata.No
publicPayloadPublic available payload.No
payloadPayload is stored encrypted in the channel.No

ChannelDataSchema​

NameTypeDescriptionRequired
linkstringYes
importeddateTimeDate when the data was imported from the tangle into the cached database.No
messageIdstringMessage id can be used to search for the message in an IOTA explorer.No
logobjectYes

ValidateBodySchema​

NameTypeDescriptionRequired
ValidateBodySchemaarray

AuthorizeSubscriptionBodySchema​

NameTypeDescriptionRequired
subscriptionLinkstringNo
idstringNo

RequestSubscriptionBodySchema​

NameTypeDescriptionRequired
seedstringIf left empty the api will generate a seed. Make sure you store the seed since the API will not store it. You can reuse your seed for different channels.No
accessRightsNo
presharedKeystringNo

RevokeSubscriptionBodySchema​

NameTypeDescriptionRequired
subscriptionLinkstringNo
idstringNo

ReimportBodySchema​

NameTypeDescriptionRequired
seedstringNo
subscriptionPasswordstringIf a subscriptionPassword is set, all data is encrypted with the password. It need to be made sure, the subscription password is sent when interacting with the APIs of the channel-service and subscription-service.No

CreateChannelResponseSchema​

NameTypeDescriptionRequired
seedstringNo
channelAddressstringYes
presharedKeystringNo

AuthorizeSubscriptionResponseSchema​

NameTypeDescriptionRequired
keyloadLinkstringYes

RequestSubscriptionResponseSchema​

NameTypeDescriptionRequired
seedstringAuto generated seed. Make sure you store the seed since the API will not store it. You can reuse your seed for different channels.Yes
subscriptionLinkstringYes

ValidateResponseSchema​

NameTypeDescriptionRequired
ValidateResponseSchemaarray

ErrorResponseSchema​

NameTypeDescriptionRequired
errorstringYes

ChannelInfoSearchSchema​

NameTypeDescriptionRequired
authorIdstringNo
namestringOptional channel name. A channel can be searched by its name.No
topicTypestringNo
topicSourcestringNo
createddateTimeNo
latestMessagedateTimeNo
limitnumberNo
indexnumberNo

SubscriptionSchema​

NameTypeDescriptionRequired
typeYes
channelAddressstringYes
idstringYes
statestringYes
subscriptionLinkstringNo
isAuthorizedbooleanYes
accessRightsYes
publicKeystringNo
keyloadLinkstringNo
sequenceLinkstringNo
pskIdstringNo

SubscriptionUpdateSchema​

NameTypeDescriptionRequired
typeNo
channelAddressstringNo
idstringNo
statestringNo
subscriptionLinkstringNo
isAuthorizedbooleanNo
accessRightsNo
publicKeystringNo
keyloadLinkstringNo
sequenceLinkstringNo
pskIdstringNo

ChannelInfoSchema​

NameTypeDescriptionRequired
channelAddressstringYes
namestringA channel can be searched by its name.Yes
descriptionstringAn optional description of the channel.No
authorIdstringYes
subscriberIds[ string ]No
topics[ object ]Yes
createddateTimeNo
latestMessagedateTimeNo

TopicSchema​

NameTypeDescriptionRequired
typestringYes
sourcestringYes

IdentityIdSchema​

NameTypeDescriptionRequired
IdentityIdSchemastring

ChannelAddressSchema​

NameTypeDescriptionRequired
ChannelAddressSchemastring