add first version of api description for the SSI service

README.md

+# 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-descriptions/jwt-credential-issue-request.md

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

jwt-descriptions/jwt-credential-issue-response.md

+# 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-descriptions/jwt-credential-verify-request.md

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

jwt-descriptions/jwt-credential-verify-response.md

+# 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-descriptions/response-jwt-create-jwt.md

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

rest-api/create-jwt.md

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

rest-api/credential-issue-request.md

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

rest-api/credential-verify-request.md

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

rest-api/register-credential-type-jolocom.md

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

rest-api/register-oganizations-credential-type copy.md

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

rest-api/register-organization.md

+# 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"
+    }
+