Commit 5e98260d authored by Peter Langenkamp's avatar Peter Langenkamp

add first version of api description for the SSI service

parent 0064b987
# Documentation for using the ssi service
These files provide a description of the REST api for interacting with the ssi service, several api’s are available.
- [Create JWT](./rest-api/create-jwt.md)
- [Credential Issue Request](./rest-api/credential-issue-request.md)
- [Credential Verify Request](./rest-api/credential-verify-request.md)
- [Register Credential Type (Jolocom)](./rest-api/register-credential-type-jolocom.md)
- [Register Organization's Credential Types](./rest-api/register-organizations-credential-types.md)
- [Register Organization](./rest-api/register-organization.md)
- [Registered Credential Type (Jolocom)](./rest-api/registered-credential-type-jolocom.md)
- [Registered Organization's Credential Types](./rest-api/registered-organizations-credential-types.md)
- [Registered Organizations](./rest-api/registered-organizations.md)
For a description of the content of jwt tokens, refer to
- [Issue Request](./jwt-descriptions/jwt-credential-issue-request)
- [Issue Response](./jwt-descriptions/jwt-credential-issue-response)
- [Verify Request](./jwt-descriptions/jwt-credential-verify-request)
- [Verify Response](./jwt-descriptions/jwt-credential-verify-request)
- [Create JWT](./jwt-descriptions/response-jwt-create-jwt)
\ No newline at end of file
# JWT for [Credential Issue Request](../rest-api/credential-issue-request.md)
The JWT should encode a JSON object with the following params. NOTE: The JWT should be created using [our API](../rest-api/create-jwt.md) to automatically include some other required parameters.
- ## `callbackUrl=[string]`
The REST api of the verifier where to deliver the credential data.
- ## `aud*=[string]`
*\*Currently added later automatically and hardcoded, but will be required in the future.*
The intended audience for the jwt (currently hardcoded as `"ssi-service-provider"`).
- ## `sub=[string]`
The type of jwt, should be `"credential-issue-request"`.
- ## `jti*=[string]`
*\*Currently added automatically (randomly generated) when [creating a jwt](../rest-api/create-jwt.md), but may be required in the future, possibly with a different name.*
A unique identifier for the JWT within the context of the issuing party, Used by the issuing party to match a response with the corresponding request.
- ## `type=[string]`
The type of credential to be issued, as defined in the ssi service. This maps to the specific credential types of the different supported wallets.
- ## `data=[object]`
Object containing the actual data to be issued. The content of this object should match the schema of the credential type.
## Example
```json
{
"callbackUrl": "http://httpbin.org/get?response=",
"aud": "ssi-service-provider",
"sub": "credential-issue-request",
"type": "FirstNameCredential",
"data": {
"firstName": "John"
}
}
```
\ No newline at end of file
# Credential Verify Response
The JWT returned to the callbackUrl specified in the [request](./jwt-credential-issue-request) encodes a JSON object with the following params.
- ## `requestId=[string]`
Identifier matching the jti in the verify request.
- ## `type=[string]`
The type of credential that was issued, as defined in the ssi service. This maps to the specific credential types of the different supported wallets.
- ## `status=[string]`
The status of the issuing. Can be `success|error|cancelled`.
- ## `connector=[string]`
The connector that was used to store the issued credentials.
- ## `iat=[number]`
The "iat" (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT.
- ## `aud*=[string]`
The "aud" (audience) claim identifies the recipients that the JWT is intended for, this should match the identifier of the issuing party (i.e. the party that issued the credentials).
- ## `iss*=[string]`
The "iss" (issuer) claim identifies the principal that issued the JWT. When receiving a JWT from the ssi service, this should be the `"ssi-service-provider"`.
- ## `sub=[string]`
The "sub" (subject) of the jwt. Should be `"credential-issue-response"`.
## Example
```json
{
"requestId": "Xks8zwLNk0A4",
"type": "FirstNameCredential",
"status": "success",
"connector": "jolocom",
"iat": 1590833726,
"aud": "40d0fbd3-38a3-4a6e-8fe9-cfc56406749d",
"iss": "ssi-service-provider",
"sub": "credential-issue-response"
}
```
\ No newline at end of file
# JWT for [Credential Verify Request](../rest-api/credential-verify-request.md)
The JWT should encode a JSON object with the following params. NOTE: The JWT should be created using [our API](../rest-api/create-jwt.md) to automatically include some other required parameters.
- ## `callbackUrl=[string]`
The REST api of the verifier where to deliver the credential data.
- ## `aud*=[string]`
*\*Currently added later automatically and hardcoded, but will be required in the future.*
The "aud" (audience) claim identifies the recipients that the JWT is intended for (currently hardcoded as `"ssi-service-provider"`).
- ## `sub=[string]`
The "sub" (subject) of the jwt. Should be `"credential-issue-request"`.
- ## `jti*=[string]`
*\*Currently added automatically (randomly generated) when [creating a jwt](../rest-api/create-jwt.md), but will be required in the future, maybe with a different name.*
A unique identifier for the JWT within the context of the verifying party. Used by the verifying party to match a response with the corresponding request.
- ## `type=[string]`
The type of credential that is requested, as defined in the ssi service. This maps to the specific credential types of the different supported wallets.
## Example
```json
{
"callbackUrl": "http://httpbin.org/get?response=",
"aud": "ssi-service-provider",
"sub": "credential-verify-request",
"type": "FirstNameCredential"
}
```
\ No newline at end of file
# Credential Verify Response
The JWT returned to the callbackUrl specified in the [request](./jwt-credential-verify-request) encodes a JSON object with the following params.
- ## `requestId=[string]`
Identifier matching the jti in the verify request.
- ## `type=[string]`
The type of credential that was requested, as defined in the ssi service. This maps to the specific credential types of the different supported wallets.
- ## `status=[string]`
The status of the request. Can be `success|error|cancelled`.
- ## `connector=[string]`
The connector that was used to provide the requested credentials.
- ## `data=[object]`
Object containing the actual data that was requested. The content of this object should matches the schema of the credential type.
- ## `iat=[number]`
The "iat" (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT.
- ## `aud*=[string]`
The "aud" (audience) claim identifies the recipients that the JWT is intended for, this should match the identifier of the verifying party.
- ## `iss*=[string]`
The "iss" (issuer) claim identifies the principal that issued the JWT. When receiving a JWT from the ssi service, this should be the `"ssi-service-provider"`.
- ## `sub=[string]`
The "sub" (subject) of the jwt. Should be `"credential-verify-response"`.
## Example
```json
{
"requestId": "55IZPT69bbFM",
"type": "FirstNameCredential",
"status": "success",
"connector": "jolocom",
"data": {
"firstName": "John"
},
"iat": 1590832865,
"aud": "40d0fbd3-38a3-4a6e-8fe9-cfc56406749d",
"iss": "ssi-service-provider",
"sub": "credential-verify-response"
}
```
\ No newline at end of file
# JWT Response to [Create JWT](../rest-api/create-jwt.md)
The JWT response adds the following params.
- ## `iat=[number]`
The "iat" (issued at) claim identifies the time at which the JWT was issued. This claim can be used to determine the age of the JWT.
- ## `aud=[string]`
The "aud" (audience) claim identifies the recipients that the JWT is intended for.
- ## `iss=[string]`
The "iss" (issuer) claim identifies the principal that issued the JWT.
- ## `jti=[string]`
The "jti" (JWT ID) claim provides a unique identifier for the JWT.
## Example:
### Submitted
```json
{
"type": "FirstNameCredential",
"callbackUrl": "https://jwt.io/"
}
```
### Decoded response
```json
{
"type": "FirstNameCredential",
"callbackUrl": "https://jwt.io/",
"iat": 1590824876,
"aud": "ssi-service-provider",
"iss": "40d0fbd3-38a3-4a6e-8fe9-cfc56406749d",
"jti": "DvzGJEoEuhpi"
}
```
\ No newline at end of file
# Create jwt
API to generate a JSON Web Token (JWT).
- ## Url
`/api/utils/jwt/:organizationId`
- ## Method
`POST`
- ## URL Params
### Required
`organizationId=[string]`
- ## Body Params
*JSON object*
### Example:
```json
{
"type": "FirstNameCredential",
"callbackUrl": "https://jwt.io/"
}
```
- ## Success Response
- ### Code
201 Created
### Content
```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiRmlyc3ROYW1lQ3JlZGVudGlhbCIsImNhbGxiYWNrVXJsIjoiaHR0cHM6Ly9qd3QuaW8vIiwiaWF0IjoxNTkwODI0ODc2LCJhdWQiOiJzc2ktc2VydmljZS1wcm92aWRlciIsImlzcyI6IjQwZDBmYmQzLTM4YTMtNGE2ZS04ZmU5LWNmYzU2NDA2NzQ5ZCIsImp0aSI6IkR2ekdKRW9FdWhwaSJ9.mjCqkRpXzdr4EXpEVSeMxNzSjFbt641qhIOWJ7y2YJ4
```
- ### Decoded JWT
```json
{
"type": "FirstNameCredential",
"callbackUrl": "https://jwt.io/",
"iat": 1590824876,
"aud": "ssi-service-provider",
"iss": "40d0fbd3-38a3-4a6e-8fe9-cfc56406749d",
"jti": "DvzGJEoEuhpi"
}
```
- ## Error Response
- ### Code
500 Internal Server Error
### Content
```json
{
"statusCode": 500,
"message": "Internal server error"
}
```
\ No newline at end of file
# Credential Issue Request
API to execute a credential issue request (i.e. use the ssi service to offer a credential to a user).
- ## Url
`/api/issue`
- ## Method
`GET`
- ## URL Params
None
- ## Query Params
### Required
`token=[string]`
This should be a jwt, as described [here](../jwt-descriptions/jwt-credential-issue-request.md).
- ## Body Params
None
- ## Success Response
- ### Code
200 OK
### Content
```json
{
"issueRequest": {
"hash": "76560bcb4f0ce284fda43721068446098b434061d8267143b6d6f72a2c1a697a",
"jwtId": "I3TBbmXS+m6H",
"requestor": {
"id": 1,
"name": "New org",
"sharedSecret": "76cd77019a62b7c1b0a665bdfec941debbff7c5360f65541016e04db12cbdac8",
"uuid": "40d0fbd3-38a3-4a6e-8fe9-cfc56406749d",
"jolocomWallet": {
"id": 1,
"encryptedSeedHex": "f82494567241333cadb3be24e8735f04fede1293109a2007e18b5381fc83f1733e899107c95c14bf6c7c0257d2a74a457e78d45570a333a9feffad1ba0faceef",
"password": "7c4c3e94eb97fa4fab723bc4c2206704"
}
},
"type": {
"id": 1,
"type": "FirstNameCredential",
"irmaType": "irma-demo.MijnOverheid.fullName",
"jolocomType": {
"id": 1,
"type": "FirstNameCredential",
"name": "First Name Credential",
"context": [
{
"lastName": "https://schema.org/givenName"
}
],
"claimInterface": {
"lastName": ""
}
}
},
"callbackUrl": "http://httpbin.org/get?response=",
"data": {
"firstName": ""
},
"id": 2,
"uuid": "c56a4cc0-9e84-469e-8978-48f762f16b24"
},
"availableConnectors": [
"jolocom"
]
}
```
- ## Error Response
- ### Code
500 Internal Server Error
### Content
```json
{
"statusCode": 500,
"message": "Internal server error"
}
```
\ No newline at end of file
# Credential Verify Request
API to execute a credential issue request (i.e. use the service to offer a credential to a user).
- ## Url
`/api/issue`
- ## Method
`GET`
- ## URL Params
None
- ## Query Params
### Required
- `token=[string]`
This should be a jwt, as described [here](../jwt-descriptions/jwt-credential-verify-request.md).
- ## Body Params
None
- ## Success Response
- ### Code
200 OK
### Content
```json
{
"verifyRequest": {
"id": 5,
"callbackUrl": "http://httpbin.org/get?response=",
"uuid": "28e1fde2-e83e-44cb-9bb1-d17a6643be52",
"jwtId": "fKFqBLnWgo8b",
"hash": "acadcc285cf49b1cbc7585e4dc70f4950f221255ee880a5a9fb6b34f13b91b63",
"type": {
"id": 1,
"type": "FirstNameCredential",
"irmaType": "irma-demo.MijnOverheid.fullName",
"jolocomType": {
"id": 1,
"type": "FirstNameCredential",
"name": "First Name Credential",
"context": [
{
"lastName": "https://schema.org/givenName"
}
],
"claimInterface": {
"lastName": ""
}
}
},
"requestor": {
"id": 1,
"name": "New org",
"sharedSecret": "76cd77019a62b7c1b0a665bdfec941debbff7c5360f65541016e04db12cbdac8",
"uuid": "40d0fbd3-38a3-4a6e-8fe9-cfc56406749d",
"jolocomWallet": {
"id": 1,
"encryptedSeedHex": "f82494567241333cadb3be24e8735f04fede1293109a2007e18b5381fc83f1733e899107c95c14bf6c7c0257d2a74a457e78d45570a333a9feffad1ba0faceef",
"password": "7c4c3e94eb97fa4fab723bc4c2206704"
}
}
},
"availableConnectors": [
"jolocom",
"irma"
]
}
```
- ## Error Response
- ### Code
500 Internal Server Error
### Content
```json
{
"statusCode": 500,
"message": "Internal server error"
}
```
\ No newline at end of file
# Register Credential Type (Jolocom)
Register a new credential type for issuing and verifying with the Jolocom app.
- ## Url
`/api/connectors/jolocom`
- ## Method
`POST`
- ## URL Params
None
- ## Body Params
*JSON object with the following params:*
### Required
`claimInterface=[object]`
`context=[object]`
`name=[string]`
`type=[string]`
### Example:
```json
{
"claimInterface": {
"firstName": ""
},
"context": [
{
"firstName": "https://schema.org/givenName"
}
],
"name": "First Name Credential",
"type": "FirstNameCredential"
}
```
- ## Success Response
- ### Code
201 Created
### Content
```json
{
"type": "FirstNameCredential",
"name": "First Name Credential",
"claimInterface": {
"firstName": ""
},
"context": [
{
"firstName": "https://schema.org/givenName"
}
],
"id": 1
}
```
- ## Error Response
- ### Code
400 Bad Request
### Content
```json
{
"statusCode": 400,
"message": [
"type should not be empty",
"type must be a string",
"context must be an array",
"claimInterface must be a non-empty object"
],
"error": "Bad Request"
}
```
\ No newline at end of file
# Register Organization's Credential Types
Register the mapping of the general credential type to those of different wallets (e.g. Irma and Jolocom)
- ## Url
`/api/types`
- ## Method
`POST`
- ## URL Params
None
- ## Body Params
*JSON object with the following params:*
### Required
`organizationId=[number]`
`type=[string]`
### Optional
`irmaType=[string]`
`jolocomCredentialTypeId=[number]`
### Example:
```json
{
"irmaType": "irma-demo.MijnOverheid.fullName",
"jolocomCredentialTypeId": 1,
"organizationId": 1,
"type": "FirstNameCredential"
}
```
- ## Success Response
- ### Code
201 Created
### Content
```json
{
"type": "FirstNameCredential",
"irmaType": "irma-demo.MijnOverheid.fullName",
"organization": {
"id": 1,
"name": "New org",
"sharedSecret": "76cd77019a62b7c1b0a665bdfec941debbff7c5360f65541016e04db12cbdac8",
"uuid": "40d0fbd3-38a3-4a6e-8fe9-cfc56406749d",
"jolocomWallet": {
"id": 1,
"encryptedSeedHex": "f82494567241333cadb3be24e8735f04fede1293109a2007e18b5381fc83f1733e899107c95c14bf6c7c0257d2a74a457e78d45570a333a9feffad1ba0faceef",
"password": "7c4c3e94eb97fa4fab723bc4c2206704"
}
},
"jolocomType": {
"id": 1,
"type": "FirstNameCredential",
"name": "First Name Credential",
"context": [
{
"lastName": "https://schema.org/givenName"
}
],
"claimInterface": {
"lastName": ""
}
},
"id": 1
}
```
- ## Error Response
- ### Code
400 Bad Request
### Content
```json
{
"statusCode": 400,
"message": [
"jolocomCredentialTypeId must be a number conforming to the specified constraints"
],
"error": "Bad Request"
}
```
- ### Code
500 Internal Server Error
### Content
```json
{
"statusCode": 500,
"message": "Internal server error"
}
```
\ No newline at end of file
# Register Organization
Register a new organization that will be able to issue or verify credentials using the ssi service. NOTE: this can take a moment to complete as it also creates, fuels and registers the required Jolocom wallet.
- ## Url
`/api/organizations/`
- ## Method
`POST`
- ## URL Params
None
- ## Body Params
*JSON object with the following params:*
### Required
`name=[string]`
### Example
```json
{
"name": "New Org"
}
```
- ## Success Response
- ### Code
201 Created
### Content
```json
{
"name": "New org",
"sharedSecret": "76cd77019a62b7c1b0a665bdfec941debbff7c5360f65541016e04db12cbdac8",
"id": 1,
"uuid": "40d0fbd3-38a3-4a6e-8fe9-cfc56406749d"
}