You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: gds-draft/approval-workflow.md
+24-13Lines changed: 24 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,10 +12,23 @@ This guide is for **David** — a data service consumer who needs to request bui
12
12
13
13
| Requirement | Description |
14
14
|-------------|-------------|
15
+
| Application registered | You have registered your application in the Self-Service Portal — see [Requesting API Access](requesting-api-access.md) Step 1 |
15
16
| API access approved | Charlie has approved your application's access to their API |
16
-
| Keyper credentials | OAuth2 client credentials for Keyper (contact Poort8 at hello@poort8.nl)|
17
+
| Keyper API access approved | You have requested access to **Keyper** for your application in the Self-Service Portal and the request is approved|
17
18
| Building details known | VBO ID of the target building and building owner's organization |
18
19
20
+
### One-time setup: Request access to Keyper
21
+
22
+
Keyper is registered as an API in the GDS Self-Service Portal, just like any other system. Before you can call the Keyper API, your application needs access to it.
23
+
24
+
1. Log in to the [Self-Service Portal](https://gds-preview.poort8.nl/portal)
25
+
2. Navigate to the **Catalogue** and search for **Keyper**
26
+
3. Click **Request Access**
27
+
28
+
Your request will have status **Pending** until approved.
29
+
30
+
> **You can continue implementing while you wait.** The repeatable steps in this guide can be built and tested independently of your access request status. Your approval requests will not go through until your application has been granted access to Keyper.
31
+
19
32
## Overview
20
33
21
34
```likec4
@@ -54,30 +67,28 @@ views {
54
67
55
68
## Step 1 — Authenticate with Keyper
56
69
57
-
Obtain an access token for the Keyper API:
70
+
Use the same M2M application credentials registered in the Self-Service Portal (see [Requesting API Access](requesting-api-access.md#step-1--register-your-application)) to request an access token. Specify `keyper-api` as the scope:
58
71
59
72
```http
60
-
POST https://poort8.eu.auth0.com/oauth/token
61
-
Content-Type: application/json
73
+
POST https://auth.poort8.nl/realms/gds-preview/protocol/openid-connect/token
74
+
Content-Type: application/x-www-form-urlencoded
62
75
63
-
{
64
-
"client_id": "<YOUR_KEYPER_CLIENT_ID>",
65
-
"client_secret": "<YOUR_KEYPER_CLIENT_SECRET>",
66
-
"audience": "Poort8-Dataspace-Keyper-Preview",
67
-
"grant_type": "client_credentials"
68
-
}
76
+
grant_type=client_credentials&
77
+
client_id=YOUR_CLIENT_ID&
78
+
client_secret=YOUR_CLIENT_SECRET&
79
+
scope=keyper-api
69
80
```
70
81
71
82
Response:
72
83
```json
73
84
{
74
85
"access_token": "eyJhbGciOiJSUzI1NiIs...",
75
86
"token_type": "Bearer",
76
-
"expires_in": 3600
87
+
"expires_in": 300
77
88
}
78
89
```
79
90
80
-
Store the token and reuse it for multiple requests until it expires (1 hour).
91
+
> **Token lifetime:** Tokens are valid for **5 minutes**. Request a new token before the current one expires. Do not cache tokens beyond their expiry.
Tokens are short-lived (5 minutes) and include an `organization` claim identifying the consumer's verified organization.
117
+
Tokens are short-lived (5 minutes) and include an `organization` claim identifying the consumer's verified organization. The same token endpoint serves both provider API calls (scope: the API's client ID) and Keyper API calls (scope: `keyper-api`), so a single registered M2M application is sufficient for all GDS interactions.
107
118
108
119
## Authorization model
109
120
@@ -178,4 +189,3 @@ Both layers must be satisfied for data to flow. A consumer needs:
178
189
| REST / JSON | All API communication |
179
190
| OpenAPI 3.x | API specification format |
180
191
| iSHARE | Policy model for authorization enforcement |
181
-
| BAG / VBO | Dutch building identification for resource IDs |
Copy file name to clipboardExpand all lines: gds-draft/onboarding.md
+11-30Lines changed: 11 additions & 30 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,44 +18,25 @@ flowchart LR
18
18
19
19
Any user can register their organization through the [Self-Service Portal](https://gds-preview.poort8.nl/portal). The registering user:
20
20
21
-
1.**Provides organization details** — KvK number (auto-verified via KvK API), organization name, VAT number (optional)
22
-
2.**Creates a user account** — name, email, and phone number
23
-
3.**Accepts conditions of use**
24
-
4.**Receives a password setup email** to activate their account
21
+
1.**Provides organization details** — KvK number, organization name
22
+
2.**Provides user details** — name, email, and phone number
23
+
3.**Receives a password setup email** to activate their account
25
24
26
-
After registration, the organization has status **"review-pending"** and awaits approval by Poort8.
25
+
After registration, the organization will be under review for approval by Poort8.
27
26
28
27
## Verifications
29
28
30
-
Each organization undergoes verification checks in three categories.
29
+
Each organization undergoes verification checks across automatic, member, and dataspace administrator-controlled steps:
31
30
32
-
### Automatic checks
33
-
34
-
These run automatically during registration:
35
-
36
-
| Check | What it does | Outcome |
37
-
|-------|-------------|---------|
38
-
|**Business register (KvK)**| Validates the KvK number via the KvK API and checks the official name | Approved if name matches; rejected if mismatch or not found |
39
-
40
-
### Organization checks
41
-
42
-
These require action from the organization's members:
43
-
44
-
| Check | What it does | Outcome |
45
-
|-------|-------------|---------|
46
-
|**Email verification**| Confirms the user's email via a verification link | Approved when user clicks the link |
47
-
48
-
### Dataspace operator checks
49
-
50
-
| Check | What it does | Outcome |
51
-
|-------|-------------|----------|
52
-
|**Onboarding approval**| Poort8's final decision on participation | Approved, rejected, or revoked |
31
+
| Verification step | Owner | What it does | Outcome |
|**Business register (KvK)**| Automatic | Validates the KvK number via the KvK API and checks the official name against the name entered during onboarding | If the name matches, onboarding continues. If it does not match, the user is asked to confirm whether they intended to onboard the KvK-registered organization |
34
+
|**Onboarding user's email verification**| Original onboarding user | Verifies that the person who started onboarding controls the submitted email address (via verification link). This user automatically becomes the organization's administrator in the dataspace. | Approved when that user confirms the email address |
35
+
|**Onboarding approval**| Dataspace administrator (Poort8) | Poort8's final decision on participation | Approved, rejected, or revoked |
53
36
54
37
## Approval process
55
38
56
-
After registration, Poort8 reviews the organization's details — including the business register check, and email verification status — and approves or rejects participation.
57
-
58
-
> **EUID cannot be changed.** If an organization registered with an incorrect KvK number, it must be deleted and re-registered with the correct details. Contact Poort8 if this occurs.
39
+
After registration, Poort8 reviews the organization's details and approves or rejects participation.
An organization must be onboarded and approved to access all dataspace features.
12
+
13
+
### Summary
14
+
15
+
1. The organization is onboarded through the Self-Service Portal
16
+
2. The onboarding user becomes the organization's first administrator
17
+
3. Poort8 reviews and approves or rejects the organization
18
+
19
+
Until Poort8 approves your organization, users from that organization cannot access dataspace systems.
20
+
21
+
For the complete onboarding and verification flow (KvK checks, email verification, and approval states), see [Organization Registration](onboarding.md).
22
+
23
+
### User roles in an organization
24
+
25
+
Users have one of two roles:
26
+
27
+
| Role | Capabilities |
28
+
|------|--------------|
29
+
|**Administrator**| Full organization management, including changing user roles and removing users |
30
+
|**Member**| Can use portal features available to the organization and invite new users |
31
+
32
+
The user who onboards the organization becomes the organization's first **administrator**.
33
+
9
34
## Portal capabilities by role
10
35
11
36
| Capability | David (Consumer) | Charlie (Provider) | Bob (Owner) |
0 commit comments