Addad integration how-to, updated structure and docs

Signed-off-by: Emiliano Suñé <emiliano.sune@gmail.com>

catalog-info.yaml

@@ -1,8 +1,8 @@
 apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:
-  name: digital-identity-and-trust-program-documentation
-  title: Digital identity and Trust Program Documentation
+  name: digital-identity-and-trust-program
+  title: Digital Identity and Trust Program
   description: Technical and non-technical documentation for Digital Trust and
     Verifiable Credentials
   annotations:

docs/acapy-integration-howto.md

@@ -0,0 +1,48 @@
+# ACA-Py Integration How-To
+
+Implementing a custom integration with an ACA-Py agent is fairly straightforward: the agent exposes a set of REST APIs that cover all of the Digital trust functionality that may be implemented. There are, however, some concepts that need to be considered when making requests to these endpoints. This page outlines some of the most important concepts and "gotchas" that need to be considered.
+
+## Authentication
+
+When requesting a new Traction tenant, you will be provided with a set of credentials that should be used to authenticate with the service (via Tenant UI and/or API endpoints). At the time of writing, the system will provide a `wallet_id` and `wallet_key` automatically upon checking-in to the system after a reservation is approved. These credentials are like a username/password combination and should be stored and protected appropriately. Losing `wallet_id` and `wallet_key` means that nobody, even the Traction administrator, will be able to recover access to your tenant. For this reason in the near future we will be switching to using exclusively `tenant_id` and `api_key` as authentication mechanism.
+
+### Tenant ID and Api Keys
+
+Similarly to `wallet_id` and `wallet_key`, `tenant_id` and `api_key` can be used to authenticate with a Traction tenant. While the value for `tenant_id` will always be the same (like a username), a tenant can independently create and delete as many API keys keys as desired. API keys can be used to provide different members of the development team with their own credentials to authenticate against a tenant, and are the preferred method to provide external applications with access to the tenant. When an API key is deleted, it ceases to function immediately and it cannot be recovered.
+
+API Keys can be managed from the section with the same name in the Tenant UI, accessible by clicking the account image in the top-right corner.
+
+### Obtaining an access token
+
+To authenticate using tenant ID and API key, execute a `POST` request to the `/multitenancy/tenant/{tenant_id}/token` endpoint. This will return a JWT that should be added in the `Authorization` header as `Bearer <jwt-that-was-obtained>` to make requests as that tenant.
+
+## Webhooks
+
+Webhooks are a fundamental tool to orchestrate asynchronous calls and sequences of requests to ACA-Py. Each tenant can specify one (or more) URLs that the agent will deliver webhooks to by accessing the *Settings* section in the tenant UI.
+
+The webhook URL must be a URL able to receive `POST` requests. A path parameter will be used by ACA-Py to specify the type of action (topic) the webhook refers to, and the body of the webhook will contain the related data.
+
+!!! info "Example"
+    If the tenant is configured to deliver webhooks to `https://my-application.example/webhooks`, a connection event will post a webhook to `https://my-application.example/webhooks/connections`.
+
+To secure the webhook endpoint, it is possible to specify a webhook key: when one is set, its value will be included in an `x-api-key` header so that the receiving application can check for it and authorize or deny the request. It is best practice to always specify an api-key to be used to protect webhook delivery and prevent unauthorized access to your service.
+
+## Persisting Transaction Data
+
+Most ACA-Py operations will trigger a webhook and while not all of them require handling, there are several scenarios where correct handling of webhooks is required to receive and store information that will be required in future interactions.
+
+### Connections
+
+When establishing a connection with another agent (mobile or not, it is indifferent), webhooks will allow your application to follow through the protocol responsible for creating the connection and, most importantly, will provide your application with the `connection_id`: this should be stored alongside the information related to the contact it belongs to, so that future interactions (sending messages, issuing/revoking credentials, requesting proofs) can be completed without having to re-establish a new contact.
+
+### Issuing Credentials
+
+When issuing credentials, webhooks will be delivered to inform the application of the current state of the issue-credential protocol. In particular, when the protocol is completed successfully two pieces of information will be produced: `revocation_id` and `revoc_reg_id` identify the specific issuance interaction and, if applicable, will be required when revoking the credential. As such, these data points should be stored by the application so that they can be retrieved and used if/when  necessary.
+
+### Other Credential Exchanges
+
+When completing credential exchange interactions (e.g.: requesting a proof), ACA-Py will create a credential exchange record that will be available only until the exchange is completed, after which it will be automatically purged. If necessary, the information about the exchange should therefore be persisted by the application.
+
+## Extra ACA-Py Settings
+
+The *Settings* page also includes extra ACA-Py settings that can be modified independently by each tenant. As an example, it is possible to increase the tenant's log level when troubleshooting. It is however recommended that these settings are left with their default value.

docs/solutions/traction-becoming-an-issuer.md

@@ -16,4 +16,4 @@ When becoming an issuer, the agent will be connected with the role of `author` t
 Endorsement requests are reviewed by the Digital Trust team and acted upon based on the published Governance. The Digital trust team may request adjustments in naming or other schema/credential definition settings in order to approve an endorsement request.
 
 !!! info "Note"
-It is generally allowed to publish new schemas and credential definitions in the development environment. Test and Production are gated behind an endorser that respects the published Governance.
+    It is generally allowed to publish new schemas and credential definitions in the development environment. Test and Production are gated behind an endorser that respects the published Governance.

docs/solutions/traction-overview.md

@@ -30,7 +30,7 @@ The following table describes the ledgers supported for both read and write oper
 | Production  | N.A.                                        | N./A.                                                         | N./A.                                                           | Write                                                           | N./A.                                                              | Write                                                           |
 
 !!! info "Note"
-An issuer can only connect to ONE ledger in write mode at any given time. Moving to another ledger is generally not recommended and it is not supported at this time.
+    An issuer can only connect to ONE ledger in write mode at any given time. Moving to another ledger is generally not recommended and it is not supported at this time.
 
 !!! warning "Limitations"
-Sovrin TestNet and MainNet ledgers are connected in write mode only for special scenarios, like temporary support of legacy issuers moving to a Traction tenant.
+    Sovrin TestNet and MainNet ledgers are connected in write mode only for special scenarios, like temporary support of legacy issuers moving to a Traction tenant.

docs/solutions/vc-authn-sso.md

@@ -19,6 +19,6 @@ There are, however, a couple of things specific to VC-AuthN that your service wi
 
 ## Limitations
 
-VC-AuthN has a different approach to "traditional" identity providers, and it does not store a user database. For this reason, and because there may be any combination of credentials in an authentication request, it is not possible for the IdP to provide a unique identifier to recognize returning users.
+VC-AuthN has a different approach when compared to "traditional" identity providers, and it does not store a user database. For this reason, and because there may be any combination of credentials in an authentication request, it is not possible for the IdP to provide a unique identifier to recognize returning users.
 
 The consuming applications (clients) are therefore responsible for reconciling user access requests to the same user by using the attributes exposed as part of the proof-request or by other mechanism.

mkdocs.yml

@@ -17,6 +17,7 @@ nav:
                             - Becoming an Issuer: solutions/traction-becoming-an-issuer.md
                   - OrgBook BC: solutions/orgbook-bc.md
                   - Endorser Service: solutions/endorser-service.md
+        - ACA-Py Integration How-to: acapy-integration-howto.md
         - About Us: about-us.md
 plugins:
         - techdocs-core