.. and press ENTER to ask a question on web5, how to write code and more.

Skip to main content
API docs by Redocly

SSI Service API (0.0.3)

Download OpenAPI specification:Download

TBD: tbd-developer@squareup.com URL: https://github.com/TBD54566975/ssi-service/issues License: Apache 2.0

The Self Sovereign Identity Service: Managing DIDs, Verifiable Credentials, and more!

ServiceInfo

Service health check

Health is a simple handler that always responds with a 200 OK

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Check service readiness

Readiness runs a number of application specific checks to see if all the relied upon services are healthy.

Responses

Response samples

Content type
application/json
{
  • "serviceStatuses": {
    },
  • "status": {
    }
}

Credentials

List Verifiable Credentials

Checks for the presence of an optional query parameter and calls the associated filtered get method. Only one optional parameter is allowed to be specified.

query Parameters
issuer
string

The issuer id, e.g. did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp

schema
string

The credentialSchema.id value to filter by

subject
string

The credentialSubject.id value to filter by

pageSize
number

Hint to the server of the maximum elements to return. More may be returned. When not set, the server will return all elements.

pageToken
string

Used to indicate to the server to return a specific page of the list results. Must match a previous requests' nextPageToken.

Responses

Response samples

Content type
application/json
{
  • "credentials": [
    ],
  • "nextPageToken": "string"
}

Create a Verifiable Credential

Create a Verifiable Credential

Request Body schema: application/json

request body

@context
string

A context is optional. If not present, we'll apply default, required context values.

required
object

Claims about the subject. The keys should be predicates (e.g. "alumniOf"), and the values can be any object.

evidence
Array of any

Optional. Corresponds to evidence in https://www.w3.org/TR/vc-data-model-2.0/#evidence

expiry
string

Optional. Corresponds to expirationDate in https://www.w3.org/TR/vc-data-model/#expiration.

issuer
required
string

The issuer id.

revocable
boolean

Whether this credential can be revoked. When true, the created VC will have the "credentialStatus" property set.

schemaId
string

A schema ID is optional. If present, we'll attempt to look it up and validate the data against it.

subject
required
string

The subject id.

suspendable
boolean

Whether this credential can be suspended. When true, the created VC will have the "credentialStatus" property set.

verificationMethodId
required
string

The id of the verificationMethod (see https://www.w3.org/TR/did-core/#verification-methods) who's privateKey is stored in ssi-service. The verificationMethod must be part of the did document associated with issuer. The private key associated with the verificationMethod's publicKey will be used to sign the credential.

Responses

Request samples

Content type
application/json
{
  • "@context": "",
  • "data": {
    },
  • "evidence": [
    ],
  • "expiry": "2029-01-01T19:23:24Z",
  • "issuer": "did:key:z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3",
  • "revocable": true,
  • "schemaId": "30e3f9b7-0528-4f6f-8aac-b74c8843187a",
  • "subject": "did:key:z6MkiTBz1ymuepAQ4HEHYSF1H8quG5GLVVQR3djdX3mDooWp",
  • "suspendable": false,
  • "verificationMethodId": "did:key:z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3#z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3"
}

Response samples

Content type
application/json
{
  • "credential": {
    },
  • "credentialJwt": "string",
  • "fullyQualifiedVerificationMethodId": "string",
  • "id": "string",
  • "revoked": true,
  • "suspended": true
}

Delete a Verifiable Credential

Delete a Verifiable Credential by its ID

path Parameters
id
required
string

ID of the credential to delete

Responses

Response samples

Content type
application/json
"string"

Get a Verifiable Credential

Get a Verifiable Credential by its ID

path Parameters
id
required
string

ID of the credential within SSI-Service. Must be a UUID.

Responses

Response samples

Content type
application/json
{
  • "credential": {
    },
  • "credentialJwt": "string",
  • "fullyQualifiedVerificationMethodId": "string",
  • "id": "string",
  • "revoked": true,
  • "suspended": true
}

Get a Verifiable Credential's status

Get a Verifiable Credential's status by the credential's ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "revoked": true,
  • "suspended": true
}

Update a Verifiable Credential's status

Update a Verifiable Credential's status

path Parameters
id
required
string

ID

Request Body schema: application/json

request body

revoked
boolean

The new revoked status of this credential. The status will be saved in the encodedList of the StatusList2021 credential associated with this VC.

suspended
boolean

Responses

Request samples

Content type
application/json
{
  • "revoked": true,
  • "suspended": true
}

Response samples

Content type
application/json
{
  • "revoked": true,
  • "suspended": true
}

Batch create Credentials

Create a batch of Verifiable Credentials.

Request Body schema: application/json

The batch requests

required
Array of objects (pkg_server_router.CreateCredentialRequest)

Required. The list of create credential requests. Cannot be more than {{.Services.CredentialConfig.BatchCreateMaxItems}} items.

Array
@context
string

A context is optional. If not present, we'll apply default, required context values.

required
object

Claims about the subject. The keys should be predicates (e.g. "alumniOf"), and the values can be any object.

evidence
Array of any

Optional. Corresponds to evidence in https://www.w3.org/TR/vc-data-model-2.0/#evidence

expiry
string

Optional. Corresponds to expirationDate in https://www.w3.org/TR/vc-data-model/#expiration.

issuer
required
string

The issuer id.

revocable
boolean

Whether this credential can be revoked. When true, the created VC will have the "credentialStatus" property set.

schemaId
string

A schema ID is optional. If present, we'll attempt to look it up and validate the data against it.

subject
required
string

The subject id.

suspendable
boolean

Whether this credential can be suspended. When true, the created VC will have the "credentialStatus" property set.

verificationMethodId
required
string

The id of the verificationMethod (see https://www.w3.org/TR/did-core/#verification-methods) who's privateKey is stored in ssi-service. The verificationMethod must be part of the did document associated with issuer. The private key associated with the verificationMethod's publicKey will be used to sign the credential.

Responses

Request samples

Content type
application/json
{
  • "requests": [
    ]
}

Response samples

Content type
application/json
{
  • "credentials": [
    ]
}

Get a Credential Status List

Get a credential status list by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "credential": {
    },
  • "credentialJwt": "string",
  • "id": "string"
}

Batch Update a Verifiable Credential's status

Updates the status all a batch of Verifiable Credentials.

Request Body schema: application/json

request body

required
Array of objects (pkg_server_router.SingleUpdateCredentialStatusRequest)

Required. The list of update credential requests. Cannot be more than the config value in services.credentials.batch_update_status_max_items.

Array
id
required
string

ID of the credential who's status should be updated.

revoked
boolean

The new revoked status of this credential. The status will be saved in the encodedList of the StatusList2021 credential associated with this VC.

suspended
boolean

Responses

Request samples

Content type
application/json
{
  • "requests": [
    ]
}

Response samples

Content type
application/json
{
  • "credentialStatuses": [
    ]
}

Verify a Verifiable Credential

Verifies a given verifiable credential. The system does the following levels of verification:

  1. Makes sure the credential has a valid signature
  2. Makes sure the credential has is not expired
  3. Makes sure the credential complies with the VC Data Model v1.1
  4. If the credential has a schema, makes sure its data complies with the schema
Request Body schema: application/json

request body

object

A credential secured via data integrity. Must have the "proof" property set.

credentialJwt
string

A JWT that encodes a credential.

Responses

Request samples

Content type
application/json
{
  • "credential": {
    },
  • "credentialJwt": "string"
}

Response samples

Content type
application/json
{
  • "reason": "string",
  • "verified": true
}

DIDConfigurations

Create DID Configurations

Creates a DID Configuration Resource which conforms to https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource The didConfiguration can be hosted at the wellKnownLocation specified in the response.

Request Body schema: application/json

request body

expirationDate
required
string

Will be used to set the DomainLinkageCredential.credentialSubject.expirationDate. Required.

issuanceDate
string

Will be used to set the DomainLinkageCredential.credentialSubject.issuanceDate. If left empty, then the current time will be used. Optional.

issuerDid
required
string

DID that identifies who the issuer of the credential(s) will be. Required.

origin
required
string

Serialization of an origin as described in https://html.spec.whatwg.org/multipage/browsers.html#origin. Represents the origin that the IssuerDID controls, which will be included in the DomainLinkageCredential.credentialSubject.origin value. Required.

verificationMethodId
required
string

The id of the verificationMethod (see https://www.w3.org/TR/did-core/#verification-methods) who's privateKey is stored in ssi-service. The verificationMethod must be part of the did document associated with issuer. The private key associated with the verificationMethod's publicKey will be used to sign the domain linkage credential. Required.

Responses

Request samples

Content type
application/json
{
  • "expirationDate": "2051-10-05T14:48:00.000Z",
  • "issuanceDate": "2021-10-05T14:48:00.000Z",
  • "issuerDid": "did:key:z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3",
  • "origin": "https://www.tbd.website/",
  • "verificationMethodId": "did:key:z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3#z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3"
}

Response samples

Content type
application/json
{
  • "didConfiguration": {
    },
  • "wellKnownLocation": "string"
}

Verifies a DID Configuration Resource

Verifies a DID Configuration Resource according to https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource-verification

Request Body schema: application/json

request body

origin
required
string

Represents an origin to fetch the DID Configuration Resource from. Must be serialized as described in https://html.spec.whatwg.org/multipage/browsers.html#origin. The scheme MUST be https.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "didConfiguration": "string",
  • "reason": "string",
  • "verified": true
}

DecentralizedIdentifiers

List DID methods

Get the list of supported DID methods

Responses

Response samples

Content type
application/json
{
  • "method": [
    ]
}

List DIDs by method

List DIDs by method. Checks for an optional "deleted=true" query parameter, which exclusively returns DIDs that have been "Soft Deleted".

path Parameters
method
required
string

Method must be one returned by GET /v1/dids

query Parameters
deleted
boolean

When true, returns soft-deleted DIDs. Otherwise, returns DIDs that have not been soft-deleted. Default is false.

pageSize
number

Hint to the server of the maximum elements to return. More may be returned. When not set, the server will return all elements.

pageToken
string

Used to indicate to the server to return a specific page of the list results. Must match a previous requests' nextPageToken.

Responses

Response samples

Content type
application/json
{
  • "dids": [
    ],
  • "nextPageToken": "string"
}

Create a DID Document

Creates a fully custodial DID document with the given method. The document created is stored internally and can be retrieved using the GetOperation. Method dependent registration (for example, DID web registration) is left up to the clients of this API. The private key(s) created by the method are stored internally never leave the service boundary.

path Parameters
method
required
string

Method

Request Body schema: application/json

request body

keyType
required
string
Enum: "Ed25519" "X25519" "secp256k1" "secp256k1-ECDSA" "P-224" "P-256" "P-384" "P-521" "RSA" "BLS12381G1" "BLS12381G2" "Dilithium2" "Dilithium3" "Dilithium5"

Identifies the cryptographic algorithm family to use when generating this key.

object

Options for creating the DID. Implementation dependent on the method.

Responses

Request samples

Content type
application/json
{
  • "keyType": "Ed25519",
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "did": {
    }
}

Soft delete a DID

When this is called with the correct did method and id it will flip the softDelete flag to true for the db entry. A user can still get the did if they know the DID ID, and the did keys will still exist, but this did will not show up in the ListDIDsByMethod call This facilitates a clean SSI-Service Admin UI but not leave any hanging VCs with inaccessible hanging DIDs. Soft deletes a DID by its method

path Parameters
method
required
string

Method

id
required
string

ID

Responses

Response samples

Content type
application/json
"string"

Get a DID

Gets a DID Document by its DID ID

path Parameters
method
required
string

Method

id
required
string

ID

Request Body schema: application/json

request body

keyType
required
string
Enum: "Ed25519" "X25519" "secp256k1" "secp256k1-ECDSA" "P-224" "P-256" "P-384" "P-521" "RSA" "BLS12381G1" "BLS12381G2" "Dilithium2" "Dilithium3" "Dilithium5"

Identifies the cryptographic algorithm family to use when generating this key.

options
any

Options for creating the DID. Implementation dependent on the method.

Responses

Request samples

Content type
application/json
{
  • "keyType": "Ed25519",
  • "options": null
}

Response samples

Content type
application/json
{
  • "did": {
    }
}

Updates a DID document.

Updates a DID for which SSI is the custodian. The DID must have been previously created by calling the "Create DID Document" endpoint. Currently, only ION dids support updates.

path Parameters
method
required
string

Method

id
required
string

ID

Request Body schema: application/json

request body

required
object

Expected to be populated when method == "ion". Describes the changes that are requested.

publicKeyIdsToRemove
Array of strings
Array of objects (ion.PublicKey)
serviceIdsToRemove
Array of strings
Array of objects (github_com_TBD54566975_ssi-sdk_did.Service)

Responses

Request samples

Content type
application/json
{
  • "stateChange": {
    }
}

Response samples

Content type
application/json
{
  • "did": {
    }
}

Batch Create DIDs

Create a batch of DIDs. The operation is atomic, meaning that all requests will succeed or fail. This is currently only supported for the DID method named did:key.

path Parameters
method
required
string

Method. Only key is supported.

Request Body schema: application/json

The batch requests

required
Array of objects (pkg_server_router.CreateDIDByMethodRequest)

Required. The list of create credential requests. Cannot be more than {{.Services.DIDConfig.BatchCreateMaxItems}} items.

Array
keyType
required
string
Enum: "Ed25519" "X25519" "secp256k1" "secp256k1-ECDSA" "P-224" "P-256" "P-384" "P-521" "RSA" "BLS12381G1" "BLS12381G2" "Dilithium2" "Dilithium3" "Dilithium5"

Identifies the cryptographic algorithm family to use when generating this key.

options
any

Options for creating the DID. Implementation dependent on the method.

Responses

Request samples

Content type
application/json
{
  • "requests": [
    ]
}

Response samples

Content type
application/json
{
  • "dids": [
    ]
}

Resolve a DID

Resolve a DID that may not be stored in this service

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "didDocument": {
    },
  • "didDocumentMetadata": {
    },
  • "didResolutionMetadata": {
    }
}

IssuanceTemplates

Create an issuance template

Creates an issuance template

Request Body schema: application/json

request body

credentialManifest
required
string

ID of the credential manifest that this template corresponds to.

Array of objects (github_com_tbd54566975_ssi-service_pkg_service_issuance.CredentialTemplate)

Info required to create a credential from a credential application.

id
string

ID of this template.

issuer
required
string

ID of the issuer that will be issuing the credentials.

verificationMethodId
required
string

The id of the verificationMethod (see https://www.w3.org/TR/did-core/#verification-methods) who's privateKey is stored in ssi-service. The verificationMethod must be part of the did document associated with issuer. The private key associated with the verificationMethod's publicKey will be used to sign the credentials.

Responses

Request samples

Content type
application/json
{
  • "credentialManifest": "string",
  • "credentials": [
    ],
  • "id": "string",
  • "issuer": "string",
  • "verificationMethodId": "did:key:z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3#z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3"
}

Response samples

Content type
application/json
{
  • "credentialManifest": "string",
  • "credentials": [
    ],
  • "id": "string",
  • "issuer": "string",
  • "verificationMethodId": "did:key:z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3#z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3"
}

Delete an issuance template

Delete an issuance template by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
"string"

Get an issuance template

Get an issuance template by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "credentialManifest": "string",
  • "credentials": [
    ],
  • "id": "string",
  • "issuer": "string",
  • "verificationMethodId": "did:key:z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3#z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3"
}

KeyStore

Store a keys

Stores a key to be used by the service

Request Body schema: application/json

request body

base58PrivateKey
required
string

Base58 encoding of the bytes that result from marshalling the private key using golang's implementation.

controller
required
id
required
string

The id field is the unique identifier for this object. If set to a resolvable DID, the ssi-service will use the private key encoded in the PrivateKeyBase58 field of this object to sign objects issued or authored by this DID; otherwise, it will only be used to identify this object.

type
required
string
Enum: "Ed25519" "X25519" "secp256k1" "secp256k1-ECDSA" "P-224" "P-256" "P-384" "P-521" "RSA" "BLS12381G1" "BLS12381G2" "Dilithium2" "Dilithium3" "Dilithium5"

Identifies the cryptographic algorithm family used with the key. One of the following: "Ed25519", "X25519", "secp256k1", "P-224", "P-256", "P-384", "P-521", "RSA".

Responses

Request samples

Content type
application/json
{
  • "base58PrivateKey": "string",
  • "controller": "string",
  • "id": "string",
  • "type": "Ed25519"
}

Response samples

Content type
application/json
"string"

Revoke a key

Marks a key as being revoked, along with the timestamps of when it was revoked. NB: the key can still be used for signing. This will likely be addressed before v1 is released.

path Parameters
id
required
string

ID of the key to revoke

Responses

Response samples

Content type
application/json
{
  • "id": "string"
}

Get details for a key

Get details about a stored key

path Parameters
id
required
string

ID of the key to get

Responses

Response samples

Content type
application/json
{
  • "controller": "string",
  • "createdAt": "string",
  • "id": "string",
  • "publicKeyJwk": {
    },
  • "type": "Ed25519"
}

Manifests

List Credential Manifests

Checks for the presence of a query parameter and calls the associated filtered get method for Credential Manifests

query Parameters
issuer
string

string issuer

schema
string

string schema

subject
string

string subject

Responses

Response samples

Content type
application/json
{
  • "manifests": [
    ]
}

Create a Credential Manifest

Create a Credential Manifest. Most fields map to the definitions from https://identity.foundation/credential-manifest/#general-composition.

Request Body schema: application/json

request body

description
string

Explains what the Manifest in question is generally offering in exchange for meeting its requirements. Optional.

required
object

Formats that the issuer can support when issuing the credential. At least one needs to be set. We currently only support jwt_vc for issuance. See https://identity.foundation/claim-format-registry/#registry for the definition. TODO: support different claim formats https://github.com/TBD54566975/ssi-service/issues/96

issuerDid
required
string

DID that identifies who the issuer of the credential(s) will be. Required.

issuerName
string

Human-readable name the Issuer wishes to be recognized by. Optional.

name
string

Summarizing title for the Manifest in question. Optional.

required
Array of objects (manifest.OutputDescriptor)
object

value of the presentation definition to use. Must be empty if id is present.

presentationDefinitionId
string

id of the presentation definition created with the PresentationDefinitions API. Must be empty if value is present.

verificationMethodId
required
string

The id of the verificationMethod (see https://www.w3.org/TR/did-core/#verification-methods) who's privateKey is stored in ssi-service. The verificationMethod must be part of the did document associated with issuer. The private key associated with the verificationMethod's publicKey will be used to sign the issued credentials. Required.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "format": {
    },
  • "issuerDid": "string",
  • "issuerName": "string",
  • "name": "string",
  • "outputDescriptors": [
    ],
  • "presentationDefinition": {
    },
  • "presentationDefinitionId": "string",
  • "verificationMethodId": "did:key:z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3#z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3"
}

Response samples

Content type
application/json
{
  • "credential_manifest": {
    }
}

Delete a Credential Manifests

Delete a Credential Manifest by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
"string"

Get a Credential Manifest

Get a Credential Manifest by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "credential_manifest": {
    },
  • "id": "string"
}

ManifestApplications

List Credential Applications

List all the existing Credential Applications.

Responses

Response samples

Content type
application/json
{
  • "applications": [
    ]
}

Submit a Credential Application

Submit a Credential Application in response to a Credential Manifest request. The request body is expected to be a valid JWT signed by the applicant's DID, containing two top level properties: credential_application and vcs according to the spec https://identity.foundation/credential-manifest/#credential-application

Request Body schema: application/json

request body

applicationJwt
required
string

A JWT signed by the applicant. The payload MUST contain the following properties:

Responses

Request samples

Content type
application/json
{
  • "applicationJwt": "string"
}

Response samples

Content type
application/json
{
  • "done": true,
  • "id": "string",
  • "result": {
    }
}

Delete Credential Applications

Delete a Credential Application by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
"string"

Get a Credential Application

Get a Credential Application by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "application": {
    },
  • "id": "string"
}

Review a Credential Application

Reviewing a Credential Application either fulfills or denies the credential(s) issuance according to the spec https://identity.foundation/credential-manifest/#credential-application.

path Parameters
id
required
string

ID

Request Body schema: application/json

request body

approved
boolean
object

Overrides to apply to the credentials that will be created. Keys are the ID that corresponds to an OutputDescriptor.ID from the manifest.

reason
string

Responses

Request samples

Content type
application/json
{
  • "approved": true,
  • "credentialOverrides": {
    },
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "credential_response": {
    },
  • "responseJwt": "string",
  • "verifiableCredentials": [
    ]
}

ManifestRequests

List Credential Manifest Requests

Lists all the existing Credential Manifest requests

Responses

Response samples

Content type
application/json
{
  • "manifestRequests": [
    ]
}

Create a Credential Manifest Request

Create a Credential Manifest Request from an existing Credential Manifest.

Request Body schema: application/json

request body

audience
Array of strings
callbackUrl
string

The URL that the presenter should be submitting the presentation submission to. Optional.

credentialManifestId
required
string

ID of the credential manifest to use for this request.

expiration
string
issuerId
required
string

DID of the issuer of this presentation definition. The DID must have been previously created with the DID API.

verificationMethodId
required
string

The id of the verificationMethod (see https://www.w3.org/TR/did-core/#verification-methods) who's privateKey is stored in ssi-service. The verificationMethod must be part of the did document associated with issuerId. The private key associated with the verificationMethod's publicKey will be used to sign an envelope that contains the created presentation definition.

Responses

Request samples

Content type
application/json
{
  • "audience": [
    ],
  • "callbackUrl": "https://example.com",
  • "credentialManifestId": "string",
  • "expiration": "string",
  • "issuerId": "string",
  • "verificationMethodId": "did:key:z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3#z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3"
}

Response samples

Content type
application/json
{
  • "manifestRequest": {
    }
}

Delete a Credential Manifest Request

Delete a Credential Manifest Request by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
"string"

Get a Credential Manifest Request

Get a Credential Manifest Request by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "manifestRequest": {
    }
}

ManifestResponses

List Credential Manifest Responses

Lists all responses to Credential Applications associated with a Credential Manifest

Responses

Response samples

Content type
application/json
{
  • "responses": [
    ]
}

Delete a Credential Manifest Response

Delete a Credential Manifest Response by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
"string"

Get a Credential Manifest Response

Get a Credential Manifest Response by its ID https://identity.foundation/credential-manifest/#credential-response

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "credential_response": {
    },
  • "responseJwt": "string",
  • "verifiableCredentials": null
}

Operations

List operations

List operations according to the request

query Parameters
parent
string

The name of the parent's resource. For example: ?parent=/presentation/submissions

filter
string

A standard filter expression conforming to https://google.aip.dev/160. For example: `?filter=done=

pageSize
number

Hint to the server of the maximum elements to return. More may be returned. When not set, the server will return all elements.

pageToken
string

Used to indicate to the server to return a specific page of the list results. Must match a previous requests' nextPageToken.

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "operations": [
    ]
}

Get an operation

Get operation by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "done": true,
  • "id": "string",
  • "result": {
    }
}

Cancel an operation

Cancels an active operation, if possible.

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "done": true,
  • "id": "string",
  • "result": {
    }
}

Presentations

List Presentation Definitions

Lists all the existing Presentation Definitions

Responses

Response samples

Content type
application/json
{
  • "definitions": [
    ]
}

Create a Presentation Definition

Create a Presentation Definition https://identity.foundation/presentation-exchange/spec/v2.0.0/#presentation-definition

Request Body schema: application/json

request body

object (exchange.ClaimFormat)
required
Array of objects (exchange.InputDescriptor)
name
string
purpose
string
Array of objects (exchange.SubmissionRequirement)

Responses

Request samples

Content type
application/json
{
  • "format": {
    },
  • "inputDescriptors": [
    ],
  • "name": "string",
  • "purpose": "string",
  • "submissionRequirements": [
    ]
}

Response samples

Content type
application/json
{
  • "presentation_definition": {
    },
  • "presentationDefinitionJwt": "string"
}

Delete a Presentation Definition

Delete a Presentation Definition by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
"string"

Get a Presentation Definition

Get a Presentation Definition by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "presentation_definition": {
    }
}

Verifies a Verifiable Presentation

Verifies a given presentation. The system does the following levels of verification:

  1. Makes sure the presentation has a valid signature
  2. Makes sure the presentation is not expired
  3. Makes sure the presentation complies with https://www.w3.org/TR/vc-data-model/#presentations-0 of VC Data Model v1.1
  4. For each credential in the presentation, makes sure: a. Makes sure the credential has a valid signature b. Makes sure the credential is not expired c. Makes sure the credential complies with the VC Data Model d. If the credential has a schema, makes sure its data complies with the schema
Request Body schema: application/json

request body

presentationJwt
required
string

A JWT that encodes a verifiable presentation according to https://www.w3.org/TR/vc-data-model/#json-web-token

Responses

Request samples

Content type
application/json
{
  • "presentationJwt": "string"
}

Response samples

Content type
application/json
{
  • "reason": "string",
  • "verified": true
}

PresentationRequests

List Presentation Requests

Lists all the existing Presentation Requests

Responses

Response samples

Content type
application/json
{
  • "presentationRequests": [
    ]
}

Create a Presentation Request

Create a Presentation Request from an existing Presentation Definition with an existing DID according to the spec https://identity.foundation/presentation-exchange/spec/v2.0.0/#presentation-request

Request Body schema: application/json

request body

audience
Array of strings
callbackUrl
string

The URL that the presenter should be submitting the presentation submission to. Optional.

expiration
string
issuerId
required
string

DID of the issuer of this presentation definition. The DID must have been previously created with the DID API.

presentationDefinitionId
required
string

ID of the presentation definition to use for this request.

verificationMethodId
required
string

The id of the verificationMethod (see https://www.w3.org/TR/did-core/#verification-methods) who's privateKey is stored in ssi-service. The verificationMethod must be part of the did document associated with issuerId. The private key associated with the verificationMethod's publicKey will be used to sign an envelope that contains the created presentation definition.

Responses

Request samples

Content type
application/json
{
  • "audience": [
    ],
  • "callbackUrl": "https://example.com",
  • "expiration": "string",
  • "issuerId": "string",
  • "presentationDefinitionId": "string",
  • "verificationMethodId": "did:key:z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3#z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3"
}

Response samples

Content type
application/json
{
  • "presentationRequest": {
    }
}

Delete a Presentation Request

Delete a Presentation Request by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
"string"

Get a Presentation Request

Get a Presentation Request by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "presentationRequest": {
    }
}

PresentationSubmissions

List Presentation Submissions

List existing Presentation Submissions according to a filtering query. The filter field follows the syntax described in https://google.aip.dev/160.

query Parameters
filter
string

A standard filter expression conforming to https://google.aip.dev/160. For example: `?filter=status=

pageSize
number

Hint to the server of the maximum elements to return. More may be returned. When not set, the server will return all elements.

pageToken
string

Used to indicate to the server to return a specific page of the list results. Must match a previous requests' nextPageToken.

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "submissions": [
    ]
}

Create a Presentation Submission

Accepts a Presentation Submission (https://identity.foundation/presentation-exchange/spec/v2.0.0/#presentation-submission) in this server ready to be reviewed.

Request Body schema: application/json

request body

submissionJwt
required
string

A Verifiable Presentation that's encoded as a JWT. Verifiable Presentation are described in https://www.w3.org/TR/vc-data-model/#presentations-0 JWT encoding of the Presentation as described in https://www.w3.org/TR/vc-data-model/#presentations-0

Responses

Request samples

Content type
application/json
{
  • "submissionJwt": "string"
}

Response samples

Content type
application/json
{
  • "done": true,
  • "id": "string",
  • "result": {
    }
}

Get a Presentation Submission

Get a Presentation Submission by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "reason": "string",
  • "status": "string",
  • "verifiablePresentation": {
    }
}

Review a pending Presentation Submission

Reviews a pending Presentation Submission. After this method is called, the operation with id==presentations/submissions/{submission_id} will be updated with the result of this invocation.

path Parameters
id
required
string

ID

Request Body schema: application/json

request body

approved
required
boolean
reason
string

Responses

Request samples

Content type
application/json
{
  • "approved": true,
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "reason": "string",
  • "status": "string",
  • "verifiablePresentation": {
    }
}

Schemas

List Credential Schemas

List Credential Schemas stored by the service

query Parameters
pageSize
number

Hint to the server of the maximum elements to return. More may be returned. When not set, the server will return all elements.

pageToken
string

Used to indicate to the server to return a specific page of the list results. Must match a previous requests' nextPageToken.

Responses

Response samples

Content type
application/json
{
  • "nextPageToken": "string",
  • "schemas": [
    ]
}

Create a Credential Schema

Create a schema for use with a Verifiable Credential

Request Body schema: application/json

request body

description
string

Description is an optional human-readable description for a schema

issuer
required
string

Issuer represents the DID of the issuer for the schema if it's signed. Required if intending to sign the schema as a credential using JsonSchemaCredential.

name
required
string

Name is a human-readable name for a schema

required
object

Schema represents the JSON schema for the credential schema If the schema has an $id field, it will be overwritten with an ID the service generates. The schema must be against draft 2020-12, 2019-09, or 7. Must include a string field $schema that must be one of https://json-schema.org/draft/2020-12/schema, https://json-schema.org/draft/2019-09/schema, or https://json-schema.org/draft-07/schema.

verificationMethodId
required
string

The id of the verificationMethod (see https://www.w3.org/TR/did-core/#verification-methods) who's privateKey is stored in ssi-service. The verificationMethod must be part of the did document associated with issuer. The private key associated with the verificationMethod's publicKey will be used to sign the schema as a credential using JsonSchemaCredential. Required if intending to sign the schema as a credential using JsonSchemaCredential.

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "issuer": "string",
  • "name": "string",
  • "schema": {
    },
  • "verificationMethodId": "did:key:z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3#z6MkkZDjunoN4gyPMx5TSy7Mfzw22D2RZQZUcx46bii53Ex3"
}

Response samples

Content type
application/json
{
  • "credentialSchema": "string",
  • "id": "string",
  • "schema": {
    },
  • "type": "JsonSchemaCredential"
}

Delete a Credential Schema

Delete a Credential Schema by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
"string"

Get a Credential Schema

Get a Credential Schema by its ID

path Parameters
id
required
string

ID

Responses

Response samples

Content type
application/json
{
  • "credentialSchema": "string",
  • "id": "string",
  • "schema": {
    },
  • "type": "JsonSchemaCredential"
}

Webhooks

List webhooks

Lists all webhooks stored by the service

Responses

Response samples

Content type
application/json
{
  • "webhooks": [
    ]
}

Create a webhook

Creates a webhook

Request Body schema: application/json

request body

noun
required
string
Enum: "Credential" "DID" "Manifest" "SchemaID" "Presentation" "Application" "Submission"

The noun (entity) for the new webhook.eg: Credential

url
required
string

The URL to post the output of this request to Noun.Verb action to.

verb
required
string
Enum: "BatchCreate" "Create" "Delete"

The verb for the new webhook.eg: Create

Responses

Request samples

Content type
application/json
{
  • "noun": "Credential",
  • "url": "string",
  • "verb": "BatchCreate"
}

Response samples

Content type
application/json
{
  • "webhook": {
    }
}

Get a webhook

Get a webhook by its ID

path Parameters
noun
required
string

noun

verb
required
string

verb

Responses

Response samples

Content type
application/json
{
  • "webhook": {
    }
}

Delete a webhook

Delete a webhook by its ID

path Parameters
noun
required
string

noun

verb
required
string

verb

url
required
string

url

Responses

Response samples

Content type
application/json
"string"

Get supported webhook nouns

Get supported nouns for webhook generation

Responses

Response samples

Content type
application/json
{
  • "nouns": [
    ]
}

Get supported webhook verbs

Get supported verbs for webhook generation

Responses

Response samples

Content type
application/json
{
  • "verbs": [
    ]
}