Skip to main content

SSI Bridge API Documentation

This is the API documentation for the SSI Bridge of the Integration Services. For further information have a look at our Wiki.

Version: v0.2

/authentication/prove-ownership/{id}

GET

Summary:

Request a nonce which must be signed by the private key

Description:

Request a nonce which must be signed by the private key of the client and send it to /prove-ownership/{identity-id} endpoint via POST. This allows a user to prove ownership of its identity public key.

Parameters
NameLocated inDescriptionRequiredSchema
idpathYesstring
Responses
CodeDescription
200Returns a nonce.
401No valid api key provided
5XXUnexpected error

POST

Summary:

Get an authentication token by signing a nonce

Description:

Get an authentication token by signing a nonce using the private key. If signature is verified, a JWT string will be returned in the response. The nonce can be received from GET /prove-ownership/{identity-id} endpoint. The JWT is used for any future API interaction.

Parameters
NameLocated inDescriptionRequiredSchema
idpathYesstring
Responses
CodeDescription
200Returns a JSON Web Token (JWT).
400No valid body provided
401No valid api key provided
500No valid signedNonce provided
5XXUnexpected error

/authentication/verify-jwt

POST

Summary:

Verify a signed jwt

Description:

Check if the jwt was signed by the Integration Service.

Responses
CodeDescription
200Returns if the jwt is valid.
400No valid body provided
401No valid api key provided
500No valid signedNonce provided
5XXUnexpected error

/identities/create

POST

Summary:

Create a new decentralized digital identity (DID)

Description:

Create a new decentralized digital identity (DID). Identity DID document is signed and published to the ledger (IOTA Tangle). A digital identity can represent an individual, an organization or an object. The privateAuthKey controlling the identity is returned. It is recommended to securely (encrypt) store the privateAuthKey locally, since it is not stored on the APIs Bridge.

Responses
CodeDescription
201Returns the created identity keys
401No valid api key provided
5XXUnexpected error
Security
Security SchemaScopes
BearerAuth
ApiKey

/identities/search

GET

Summary:

Search for identities

Description:

Search for identities in the system and returns a list of existing identities.

Parameters
NameLocated inDescriptionRequiredSchema
typequeryNostring
usernamequeryNostring
creatorqueryNostring
registration-datequeryNodateTime
limitqueryNonumber
indexqueryNonumber
ascqueryNoboolean
Responses
CodeDescription
200Return list of existing entities.
401No valid api key provided / Not authenticated
5XXUnexpected error
Security
Security SchemaScopes
BearerAuth
ApiKey

/identities/identity/{id}

GET

Summary:

Get information about a specific identity

Description:

Get information (including attached credentials) about a specific identity using the identity-id (DID identifier).

Parameters
NameLocated inDescriptionRequiredSchema
idpathYesstring
Responses
CodeDescription
200Return a specific identity / none if no identity exits with given identity-id
401No valid api key
5XXUnexpected error

DELETE

Summary:

Removes an identity from the Bridge

Description:

Removes an identity from the Bridge. An identity can only delete itself and is not able to delete other identities. Administrators are able to remove other identities. The identity cannot be removed from the immutable IOTA Tangle but only at the Bridge. Also the identity credentials will remain and the identity is still able to interact with other bridges.

Parameters
NameLocated inDescriptionRequiredSchema
idpathYesstring
revoke-credentialsqueryIf true all credentials will be revoked and deleted.Noboolean
revoke-subscriptionsqueryIf true all subscriptions will be revoked and deleted.Noboolean
Responses
CodeDescription
200Deleted Identity.
401No valid api key provided / Not authenticated
5XXUnexpected error
Security
Security SchemaScopes
BearerAuth
ApiKey

/identities/identity

POST

Summary:

Register an existing identity into the Bridge

Description:

Register an existing identity into the Bridge. This can be used if the identity already exists or it was only created locally. Registering an identity in the Bridge makes it possible to search for it by using some of the identity attributes, i.e., the username.

Responses
CodeDescription
200The registered entity.
401No valid api key
5XXUnexpected error

PUT

Summary:

Update claim of a registered identity

Description:

Update claim of a registered identity.

Responses
CodeDescription
200The registered entity.
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

/verification/latest-document/{id}

GET

Summary:

Get the latest version of an identity document (DID)

Description:

Get the latest version of an identity document (DID) from the IOTA Tangle.

Parameters
NameLocated inDescriptionRequiredSchema
idpathYesstring
Responses
CodeDescription
200Latest Identity document (DID)
401No valid api key provided
5XXUnexpected error

/verification/trusted-roots

POST

Summary:

Adds Trusted Root identity identifiers (DIDs)

Description:

Adds Trusted Root identity identifiers (DIDs). Trusted roots are DIDs of identities which are trusted by the Bridge. This identity DIDs can be DIDs of other organizations. By adding them to the list Trusted Roots their Verifiable Credentials (VCs) are automatically trusted when checking at the Bridge.

Responses
CodeDescription
200Successful added trusted Root identity identifier.
401No valid api key provided / Not authenticated / Not authorized
5XXUnexpected error
Security
Security SchemaScopes
BearerAuth
ApiKey

GET

Summary:

Returns a list of Trusted Root identity identifiers (DIDs)

Description:

Returns a list of Trusted Root identity identifiers (DIDs). Trusted roots are DIDs of identities which are trusted by the Bridge. This identity DIDs can be DIDs of other organizations. By adding them to the list Trusted Roots their Verifiable Credentials (VCs) are automatically trusted when checking at the Bridge.

Responses
CodeDescription
200List of Trusted Root identity identifiers (DIDs).
401No valid api key provided
5XXUnexpected error

/verification/trusted-roots/{trustedRootId}

DELETE

Summary:

Remove Trusted Root identity identifiers (DIDs)

Description:

Remove Trusted Root identity identifiers (DIDs). Trusted roots are DIDs of identities which are trusted by the Bridge. This identity DIDs can be DIDs of other organizations. By adding them to the list Trusted Roots their Verifiable Credentials (VCs) are automatically trusted when checking at the Bridge.

Parameters
NameLocated inDescriptionRequiredSchema
trustedRootIdpathYesstring
Responses
CodeDescription
200Successful removed trusted Root identity identifier.
401No valid api key provided / Not authenticated / Not authorized
5XXUnexpected error
Security
Security SchemaScopes
BearerAuth
ApiKey

/verification/create-credential

POST

Summary:

Verify the authenticity of an identity and issue a credential

Description:

Verify the authenticity of an identity (of an individual, organization or object) and issue a credential stating the identity verification status. Only previously verified identities (based on a network of trust) with assigned privileges can verify other identities. Having a verified identity provides the opportunity for other identities to identify and verify a the entity they interact to.

Responses
CodeDescription
200The created credential.
401No valid api key provided / Not authenticated
5XXUnexpected error
Security
Security SchemaScopes
BearerAuth
ApiKey

/verification/check-credential

POST

Summary:

Check the verifiable credential of an identity

Description:

Check the verifiable credential of an identity. Validates the signed verifiable credential against the Issuer information stored onto the IOTA Tangle and checks if the issuer identity (DID) contained in the credential is from a trusted root.

Responses
CodeDescription
200The registered entity.
401No valid api key provided
5XXUnexpected error

/verification/revoke-credential

POST

Summary:

Revoke one specific verifiable credential of an identity

Description:

Revoke one specific verifiable credential of an identity. In the case of individual and organization identities the reason could be that the user has left the organization. Only organization admins (with verified identities) or the identity owner itself can do that.

Responses
CodeDescription
200Revoke successful
401No valid api key provided / Not authenticated
5XXUnexpected error
Security
Security SchemaScopes
BearerAuth
ApiKey

Models

ProveOwnershipPostBodySchema

NameTypeDescriptionRequired
signedNoncestringYes

CreateChannelBodySchema

NameTypeDescriptionRequired
namestringA channel can be searched by its name.No
descriptionstringAn optional description for a channel.No
typeChannel type used to differ between public and private channels.No
hiddenbooleanIf set to true the channel can not be found by others. It will be still possible to give specific users access to the channel.No
visibilityList[ object ]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
sourceobjectNo
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

RevokeVerificationBodySchema

NameTypeDescriptionRequired
signatureValuestringYes

CreateCredentialBodySchema

NameTypeDescriptionRequired
subjectobjectYes
initiatorVCobjectNo

VerifiableCredentialBodySchema

NameTypeDescriptionRequired
@contextstringYes
idstringYes
type[ string ]Yes
credentialSubjectobjectYes
issuerstringYes
issuanceDatedateTimeYes
credentialStatusobjectNo
proofobjectYes

TrustedRootBodySchema

NameTypeDescriptionRequired
trustedRootIdstringYes

SubjectBodySchema

NameTypeDescriptionRequired
idstringYes
credentialTypestringYes
claimobjectYes

CreateIdentityBodySchema

NameTypeDescriptionRequired
storeIdentitybooleanNo
usernamestringYes
registrationDatedateTimeNo
creatorstringNo
rolestringNo
claimobjectNo
hiddenbooleanNo
isServerIdentitybooleanNo
verifiableCredentials[ object ]No

UpdateIdentityBodySchema

NameTypeDescriptionRequired
idstringYes

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
subscriberIdstringNo
requestedSubscriptionIdstringNo
namestringOptional channel name. A channel can be searched by its name.No
hiddenbooleanChannels which are hidden to others.No
channelTypeChannel type used to differ between public and private channels.No
topicTypestringNo
topicSourcestringNo
createddateTimeNo
latestMessagedateTimeNo
limitnumberNo
indexnumberNo
ascendingbooleanSorting the channels by creation date ascending or descendingNo

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

ClaimSchema

NameTypeDescriptionRequired
typeYes

ChannelInfoSchema

NameTypeDescriptionRequired
channelAddressstringYes
namestringA channel can be searched by its name.Yes
descriptionstringAn optional description of the channel.No
hiddenbooleanIf set to true the channel can not be found by others. It will be still possible to give specific users access to the channel.No
visibilityList[ object ]No
typeChannel type used to differ between public and private channels.No
authorIdstringYes
subscriberIds[ string ]No
requestedSubscriptionIds[ string ]No
topics[ object ]Yes
createddateTimeNo
latestMessagedateTimeNo

TopicSchema

NameTypeDescriptionRequired
typestringYes
sourcestringYes

VerifiableCredentialSubjectSchema

NameTypeDescriptionRequired
idstringYes
typestringYes
initiatorstringNo

VerifiableCredentialSchema

NameTypeDescriptionRequired
@contextstringYes
idstringYes
type[ string ]Yes
credentialSubjectobjectYes
issuerstringYes
issuanceDatedateTimeYes
credentialStatusobjectNo
proofobjectYes

IdentitySchema

NameTypeDescriptionRequired
idstringYes
usernamestringYes
registrationDatedateTimeNo
creatorstringNo
rolestringNo
claimobjectNo
hiddenbooleanNo
isServerIdentitybooleanNo
verifiableCredentials[ object ]No

IdentityKeyPairSchema

NameTypeDescriptionRequired
typestringYes
publicstringYes
privatestringYes
encodingYes

KeysSchema

NameTypeDescriptionRequired
signobjectYes
encryptobjectNo

IdentityKeysSchema

NameTypeDescriptionRequired
idstringYes
keysobjectYes

IdentityDocumentSchema

NameTypeDescriptionRequired
docobjectYes
metaobjectYes
proofobjectYes
integrationMessageIdstringNo

LatestIdentityDocSchema

NameTypeDescriptionRequired
documentobjectYes
messageIdstringYes

DeviceSchema

Device schema, see the specification at: https://github.com/smart-data-models/dataModel.Device/blob/master/Device/doc/spec.md or https://github.com/smart-data-models/dataModel.Device/blob/master/DeviceModel/doc/spec.md or https://petstore.swagger.io/?url=https://smart-data-models.github.io/dataModel.Device/Device/swagger.yaml#/ngsi-ld/get_ngsi_ld_v1_entities

NameTypeDescriptionRequired
@contextstringNo
typestringNo
alternateNamestringNo
namestringNo
descriptionstringNo
urlstringNo
imageNo
sameAsNo
category[ ]Yes
controlledProperty[ ]Yes
addressobjectPostalAddress schema, see the specification at: https://schema.org/PostalAddressNo
batteryLevelnumberNo
configurationNo
controlledAssetNo
dataProviderNo
dateFirstUseddateTimeNo
dateInstalleddateTimeNo
dateLastCalibrationdateTimeNo
dateLastValueReporteddateTimeNo
dateManufacureddateTimeNo
deviceStatestringNo
directionNo
distancenumberNo
dstAwarebooleanNo
depthnumberNo
firmwareVersionstringNo
hardwareVersionstringNo
ipAddress[ string ]No
locationNo
macAddress[ string ]No
mccstringNo
mncstringNo
osVersionstringNo
ownerNo
providerNo
refDeviceModelNo
relativePositionstringNo
rssiNo
serialNumberstringNo
softwareVersionstringNo
sourceNo
supportedProtocolNo
valueNo

OrganizationSchema

Organization schema, see the specification at: https://schema.org/Organization

NameTypeDescriptionRequired
@contextstringNo
typestringNo
alternateNamestringNo
namestringNo
descriptionstringNo
urlstringNo
imageNo
sameAsNo
brandNo
addressNo
emailstringNo
faxNumberstringNo
locationstringNo
sloganstringNo
taxIDstringNo
telephonestringNo
vatIDstringNo

PersonSchema

Person schema, see the specification at: https://schema.org/Person

NameTypeDescriptionRequired
@contextstringNo
typestringNo
alternateNamestringNo
namestringNo
descriptionstringNo
urlstringNo
imageNo
sameAsNo
familyNamestringNo
givenNamestringNo
memberOfNo
worksForNo
addressNo
colleagueNo
emailstringNo
jobTitlestringNo
birthDatedateNo
heightNo
weightNo
genderstringNo
nationalitystringNo
telephonestringNo

ProductSchema

Product schema, see the specification at: https://schema.org/Product

NameTypeDescriptionRequired
@contextstringNo
typestringNo
alternateNamestringNo
namestringNo
descriptionstringNo
urlstringNo
imageNo
sameAsNo
aggregateRatingobjectAggregateRating schema, see the specification at: https://schema.org/AggregateRatingNo
awardstringNo
brandNo
category[ string ]No
colorstringNo
gtinstringNo
heightNo
logostringNo
manufacturerobjectOrganization schema, see the specification at: https://schema.org/OrganizationNo
materialNo
modelstringNo
mpnstringNo
nsnstringNo
offersNo
patternstringNo
productIDstringNo
productionDatedateTimeNo
purchaseDatedateTimeNo
releaseDatedateTimeNo
reviewobjectReview schema, see the specification at: https://schema.org/ReviewNo
sizeNo
skustringNo
sloganstringNo
weightNo
widthNo

ServiceSchema

Service schema, see the specification at: https://schema.org/Service

NameTypeDescriptionRequired
@contextstringNo
typestringNo
alternateNamestringNo
namestringNo
descriptionstringNo
urlstringNo
imageNo
sameAsNo
aggregateRatingobjectAggregateRating schema, see the specification at: https://schema.org/AggregateRatingNo
availableChannelobjectNo
brandNo
categorystringNo
offersNo
providerNo
reviewNo
serviceOutputNo
serviceTypestringNo
termsOfServicestringNo

IdentitySearchBodySchema

NameTypeDescriptionRequired
idstringYes
numberOfCredentialsintegerNumber of credentials connected to this identityYes
usernamestringYes
registrationDatedateTimeNo
creatorstringNo
rolestringNo
claimobjectNo
hiddenbooleanNo
isServerIdentitybooleanNo

IdentityIdSchema

NameTypeDescriptionRequired
IdentityIdSchemastring

NonceSchema

NameTypeDescriptionRequired
noncestringYes

ChannelAddressSchema

NameTypeDescriptionRequired
ChannelAddressSchemastring

VerifyJwtBodySchema

NameTypeDescriptionRequired
jwtstringYes