Review changes (#6)

* Naming and small fixes

* Unpublish events, since it doesn't contain anything actionable

* Clean up sandbox documentation

* Clarify work to be done

* Small fixups on writing a service

* Disable code samples chapter

* Troubleshooting guides for specific components are out of scope

These kinds of guides should be part of the component's documentation.

* Rewording

association-registry.md → association-register.md

@@ -1,16 +1,16 @@
 ---
-title: Association Registry
+title: Association Register
 category: 4. Components
 order: 2
 ---
 
-The Association Registry, unlike the Authorization Registry, is a registry run by a central authority. It contains a list of authorized participants in an iSHARE Data Space. For each listed participant, it stores their current compliance status, the time frame during which that status applies, their endpoint, and a list of Authorization Registries that manage access to the participants. It also contains additional information, including legal details such as agreements.
+The Association Register, unlike the Authorization Register, is a register run by a central authority. It contains a list of authorized participants in an iSHARE Data Space. For each listed participant, it stores their current compliance status, the time frame during which that status applies, their endpoint, and a list of Authorization Registries that manage access to the participants. It also contains additional information, including legal details such as agreements.
 
-To interact with an Association Registry, clients first need to obtain a token by sending a message containing their ID, among other details, and signing it with their private key. This message is called a Client Assertion. The Association Registry will use the supplied ID to look up the client's public key. With the public key, it will verify the signature. If the signature is valid and the client's current status is active, the registry will generate a token, store it internally along with an expiration date, and send it to the client.
+To interact with an Association Register, clients first need to obtain a token by sending a message containing their ID, among other details, and signing it with their private key. This message is called a Client Assertion. The Association Register will use the supplied ID to look up the client's public key. With the public key, it will verify the signature. If the signature is valid and the client's current status is active, the register will generate a token, store it internally along with an expiration date, and send it to the client.
 
-With this token, clients may use the API of the Association Registry. Using the [parties API-call](https://dev.ishare.eu/satellite/parties.html#request), clients may access data of a specific party, specified by their [EORI-id](glossary.id#EORI).
+With this token, clients may use the API of the Association Register. Using the [single party API-call](https://dev.ishare.eu/ishare-satellite-role/single-party), clients may access data of a specific party, specified by their [EORI-id](glossary.md#EORI).
 
-##### Core Functions of the Association Registry
+##### Core Functions of the Association Register
 
 ###### Compliance Status Management
 
@@ -20,7 +20,7 @@ With this token, clients may use the API of the Association Registry. Using the
 ###### Participant Endpoints
 - Stores the endpoint information of each participant, enabling other participants to discover and interact with them directly.
 
-###### Authorization Registry References
+###### Authorization Register References
 - Lists the Authorization Registries associated with each participant. These registries manage detailed access control policies and permissions for data sharing.
 
 ###### Legal and Contractual Information

authorization-registry.md → authorization-register.md

@@ -1,15 +1,12 @@
 ---
-title: Authorization Registry
+title: Authorization Register
 category: 4. Components
 order: 3
 ---
 
-### About the Authorization Registry
+Within a Data Space, The Authorization Register manages and enforces access control policies. Its core functions revolve around ensuring that data access is granted based on predefined rules and that only authorized participants can access specific data or services. Here are the core functions of the Authorization Register:
 
-
-The Authorization Registry in a Data Space, such as the iSHARE Data Space, is a critical component that manages and enforces access control policies. Its core functions revolve around ensuring that data access is granted based on predefined rules and that only authorized participants can access specific data or services. Here are the core functions of the Authorization Registry:
-
-#### Core Functions of the Authorization Registry
+#### Core Functions of the Authorization Register
 
 
 ##### Access Control Policy Management:
@@ -54,7 +51,7 @@ Dynamic Roles: Allows for dynamic assignment of roles based on context and chang
 
 #### Main API Call
 
-The main API-call of the Authorization Registry is the `/delegation` call. It is used to pass a delegation mask, or delegation request, to the AR, and to receive a Delegation Evidence, a JWT, in response. A Delegation Mask contains an issuer and a target, and a set of policies. Each policy contains (desired) rules (e.g. "Effect: permit"), and a target. The target contains a resource, an environment, and a list of actions (e.g. create, read, update, delete). Together, the policies represent the right to take specified actions on a specified set of resources.
+The main API-call of the Authorization Register is the `/delegation` call. It is used to pass a delegation mask, or delegation request, to the AR, and to receive a Delegation Evidence, a JWT, in response. A Delegation Mask contains an issuer and a target, and a set of policies. Each policy contains (desired) rules (e.g. "Effect: permit"), and a target. The target contains a resource, an environment, and a list of actions (e.g. create, read, update, delete). Together, the policies represent the right to take specified actions on a specified set of resources.
 
 The Delegation Evidence is practically identical to the Delegation Mask. It also contains an issuer, a target, and a set of policies, and in addition it contains a time frame in which the Delegation Evidence is valid, and a few other values, such as the license for the target, and a maximum delegation depth.
 

available-components.md

@@ -10,20 +10,19 @@ Several components are available for BDI implementations.
 
 ### [FIWARE iSHARE Satellite](https://github.com/FIWARE/ishare-satellite)
 
-A simple implementation of an iSHARE satellite trust anchor.
+A simple implementation of an iSHARE satellite trust anchor / BDI Assocation Register.
 
-It is based on Python Flask using gunicorn and runs completely stateless. It is configured with a static configuration file.
+The FIREWARE iSHARE Satellite is based on Python Flask using gunicorn and runs completely stateless. It is configured with a static configuration file.
 
 _This implementation of the iSHARE Satellite is only meant for testing and demonstration purposes. It is not possible to change participants or trusted CAs in a running instance. It is not recommended to be used in production environments._
 
 ### [Poort8 Dataspace Noodle Bar](https://github.com/POORT8/Poort8.Dataspace.NoodleBar)
 
-Poort8 Noodlebar
+The Noodle Bar project falls under the Basic Data Infrastructure umbrella, pending its ongoing development.
 
-The project is under the Basis Data Infrastructuur (BDI) umbrella, pending its ongoing development.
+Noodle Bar facilitates setting up dataspaces that follow certain principles, serving as an initial platform for data providers, apps, and data consumers.
 
-To facilitate setting up dataspaces that follow certain principles, serving as an initial platform for data providers, apps, and data consumers.
-Roles
+**Roles**
 
  - Data Providers: Organizations that either offer a data source with raw data or an app with processed data. In all cases, access conditions are set by the data owner.
  - App Providers: Organizations that act as intermediaries, adding value to raw data. They act as a Data Consumer on behalf of their end users, and as a Data Provider for their end users.
@@ -36,10 +35,10 @@ This is official iSHARE library which provides core functionality for service co
 
 ### [iSHARE Authorization Registry](https://github.com/iSHAREScheme/AuthorizationRegistry)
 
-_The Authorization Registry-code that is in this repository is not a 'production-ready' Authorization Registry, meaning it has a limited set of functionalities. It can be used in proof of concepts or pilots to showcase the iSHARE Authorization protocol, however many functionalities can be improved. Furthermore, it should be noted that only the request and return made to the /delegation endpoint (as described on our Developer Portal) is specified within the iSHARE standards. How an authorization registry registers policies and translates these into delegation evidence is up to the authorization registry. This code only provides one of the options to do so._
+_The Authorization Register-code that is in this repository is not a 'production-ready' Authorization Register, meaning it has a limited set of functionalities. It can be used in proof of concepts or pilots to showcase the iSHARE Authorization protocol, however many functionalities can be improved. Furthermore, it should be noted that only the request and return made to the /delegation endpoint (as described on our Developer Portal) is specified within the iSHARE standards. How an authorization registry registers policies and translates these into delegation evidence is up to the authorization registry. This code only provides one of the options to do so._
 
 ### [iSHARE Satellite](https://github.com/iSHAREScheme/iSHARESatellite)
 
-This is the iSHARE equivalant of a BDI Assocation Register.
+This is the iSHARE equivalant of a BDI Association Register.
 
 The iSHARE satellite is an application that safeguards trust in a dataspace. It functions as a register of participants. Participants can call the satellite API to verify each other. When you verify that a participant is registered in the satellite, you know that this participant has signed which agreements and the participant is indeed a part of a dataspace, also on a "legal level".

code-samples.md

@@ -1,7 +1,7 @@
 ---
-title: Code Samples
-category: 8. Code Samples
-order: 1
+# title: Code Samples
+# category: 8. Code Samples
+# order: 1
 ---
 
 I'm guessing that code samples involve implementing a resource to use the response given by AuthoReg (including the delegation evidence). Specifically, how to check if the token and the delegation evidence are valid.

events.md

@@ -1,7 +1,7 @@
 ---
-title: Events
-category: 3. What Is BDI
-order: 3
+# title: Events
+# category: 3. What Is BDI
+# order: 3
 ---
 
 TODO Very little concrete information so summarizing what's on the BDI page

how-it-works.md

@@ -6,6 +6,6 @@ order: 3
 
 The Basic Data Infrastructure (BDI) is a system designed to help different organizations share data safely and efficiently. Think of it as a giant, organized library where various entities, like businesses and government agencies, can store their data and also access data from others. This library has strict rules to make sure that only the right people can access the right data, ensuring that everything stays secure and private.
 
-In this system, each participant has a unique identity, like a library card, which is used to verify who they are. When an organization wants to access or share data, they use this identity to authenticate themselves. The BDI uses digital keys and signatures to check these identities and ensure that only authorized participants can see or use the data. This process is managed by a set of registries that keep track of who is who and what permissions they have, similar to a librarian checking if you have the right library card to borrow a book.
+In this system, each participant has a unique identity, like a library card, which is used to verify who they are. When an organization wants to access or share data, they use this identity to authenticate themselves. The BDI uses digital keys and signatures to check these identities and ensure that only authorized participants can see or use the data. This process is managed by a set of registers that keep track of who is who and what permissions they have, similar to a librarian checking if you have the right library card to borrow a book.
 
 Another important feature of BDI is its decentralized nature. Instead of having one central authority controlling everything, BDI is made up of many interconnected parts that work together. These parts share information and coordinate to make sure the system runs smoothly. This setup makes BDI more flexible and resilient, as it can easily adapt to new participants and changing needs, all while maintaining high standards of security and trust.

index.md

@@ -1,16 +1,16 @@
 ---
-title: Introduction
+title: BDI Developer Portal Introduction
 category: 1. Introduction
 order: 1
 ---
 
 #### Audience
 
-This site is a BDI developers portal, meant for developers who need to access a Service Provider, write a Service Provider, or even implement an Authorization register, or who just need to know how BDI works.
+This site is the [Basic Data Infrastructure](what-is-bdi.md) (BDI) developer portal, meant for developers who need to access a Service Provider, write a Service Provider, or even implement an Authorization Register, or who just need to know how BDI works.
 
 #### Purpose Of BDI
 
-The purpose of BDI and iSHARE is to provide a standardized, secure, and interoperable framework for efficient and trusted data sharing within and between organizations.
+The purpose of BDI is to provide a standardized, secure, and interoperable framework for efficient and trusted data sharing within and between organizations.
 
 #### Advantages
 

sandbox.md

@@ -1,16 +1,31 @@
 ---
-title: Sandbox
+title: Sandbox Environment
 category: 5. Sandbox
 order: 1
 width: 800
 ---
 
-In order to test a component against an Association Registry or Authentication Registry, there are two options. You can download and run the components on this website, or you can use one of the existing sandbox environments.
+In order to test a component against an Association Registry or Authentication Registry, there are two options. You can download and run the components on this website, or you can use an existing sandbox environment.
 
-There are three existing sandbox environments. In order to get access to them, please request access from their administrators.
+The BDI maintains a public sandbox environment with three services. In order to get access to them, please request access from their administrators.
 
-| Name | URL | Swagger | EORI-ID |
-| ---- | --- | ------- | ------- |
-| iSHARE Test Authorisation Registry | [isharetest](https://ar.isharetest.net/) | [Swagger](https://ar.isharetest.net/swagger/index.html) | EU.EORI.NL000000004 |
-| BDI Association Registry | [iSHARE](https://dilsat1.pg.bdinetwork.org/) | - | EU.EORI.NLDILSATTEST1 |
-| Poort8 Authorisation Registry | [Poort8](https://tsl-ishare-dataspace-coremanager-preview.azurewebsites.net/api/ishare) | - | EU.EORI.NLP8TSLAR1 |
+* iSHARE Test Authorisation Registry
+
+ - URL: (https://ar.isharetest.net/
+ - API Docs: https://ar.isharetest.net/swagger/index.html
+ - Server ID: `EU.EORI.NL000000004`
+ - Administrator email: <[email protected]>
+
+* BDI Association Register
+
+An instance of the iSHARE Satellite server
+
+  - URL: https://dilsat1.pg.bdinetwork.org/
+  - API Docs: https://dev.ishare.eu/ishare-satellite-role/getting-started
+  - Server ID: `EU.EORI.NLDILSATTEST1`
+
+* Poort8 Authorization Register
+
+  - URL: https://tsl-ishare-dataspace-coremanager-preview.azurewebsites.net/api/ishare
+  - API Docs: https://github.com/POORT8/Poort8.Dataspace.NoodleBar/blob/main/docs/APIdocs.md
+  - Server ID: `EU.EORI.NLP8TSLAR1`

service-discovery.md

@@ -4,7 +4,7 @@ category: 6. Writing a client
 order: 2
 ---
 
-TODO: Make this more low level and concrete
+TODO: Include references to two ways of service discovery: 1. via Association Register party info, 2. via DNS (pdf document)
 
 Service discovery in the context of Basic Data Infrastructure (BDI) is a crucial mechanism that helps participants locate and access various services within a vast and interconnected digital network. Imagine it as an advanced directory system that knows where all the services, such as data storage, analytics tools, and application interfaces, are located. This directory system ensures that participants can easily find and use these services without needing to know their specific locations or endpoints in advance.
 

writing-a-service.md

@@ -10,8 +10,8 @@ When designing a new API in the Logistics sector, we recommend using existing st
 
 ## BDI Enabling
 
-To extend a service provider API and make it iSHARE compatible, you will need to take an existing HTTP service and add a /token endpoint to it, which will first check whether the client assertion in the request is valid and addressed to you. You will perform get a token from the Association Registry, and then use it to perform a /party call there to lookup information on the client based on the client id included in the client assertion. If the party information shows that the client is compliant, then you can return a token to the client.
+To extend a service provider API and make it BDI compatible, at minimum you will need to provide the `/connect/token` endpoint to provide access tokens for use in further API calls. The `/connect/token` endpoint which will first check whether the client assertion in the request is valid and addressed to the server. You will perform get a token from the Association Registry, and then use it to perform a /party call there to lookup information on the client based on the client id included in the client assertion. If the party information shows that the client is compliant, then you can return a token to the client.
 
-Also, you'll have to extend all API calls with a check to see whether they include a valid token in the header, and also a check to see if they include a delegation evidence JWT. That JWT should be valid (right sender and recipient, and signed correctly) and the policies in its payload should allow access to the current API call.
+Also, you'll have to extend all API calls with a check to see whether they include a valid token in the header, and check to see if they include a delegation evidence JWT. That JWT should be valid (right sender and recipient, and signed correctly) and the policies in its payload should allow access to the current API call.
 
 If all that is correct, the API call may proceed.