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: 1.0.0

Endpoints

/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

/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
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.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

RevokeVerificationBodySchema

NameTypeDescriptionRequired
signatureValuestringYes

CreateCredentialBodySchema

NameTypeDescriptionRequired
subjectobjectYes
initiatorVCobjectNo

VerifiableCredentialBodySchema

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

TrustedRootBodySchema

NameTypeDescriptionRequired
trustedRootIdstringYes

SubjectBodySchema

NameTypeDescriptionRequired
idstringYes
credentialTypestringYes
claimobjectYes

CreateIdentityBodySchema

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

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
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

ClaimSchema

NameTypeDescriptionRequired
typeYes

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

VerifiableCredentialSubjectSchema

NameTypeDescriptionRequired
idstringYes
typestringYes
initiatorIdstringNo

VerifiableCredentialSchema

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

IdentityJsonSchema

NameTypeDescriptionRequired
docobjectYes
keyobjectYes

IdentityKeyPairJsonSchema

NameTypeDescriptionRequired
typestringYes
publicstringYes
secretstringYes
encodingYes

IdentityDocumentJsonSchema

NameTypeDescriptionRequired
idstringYes
verificationMethod[ object ]No
previousMessageIdstringNo
authentication[ object ]Yes
createddateTimeYes
updateddateTimeYes
immutablebooleanYes
proofobjectYes

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

IdentitySchema

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

IdentitySearchBodySchema

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

IdentityIdSchema

NameTypeDescriptionRequired
IdentityIdSchemastring

NonceSchema

NameTypeDescriptionRequired
noncestringYes

ChannelAddressSchema

NameTypeDescriptionRequired
ChannelAddressSchemastring