Organizations

Overview
The Organizations feature adds a way for your organization to connect with users and allows you to:
Share the personal data your organization has about a given user with them in a secure and private channel (to comply with GDPR for example).
Have data shared with your organization from a given user in a secure and private channel with explicit consent and have the data updated by the user automatically updated in your company's systems.
Setting up an Organization
Assuming you have followed the guide from the quickstart section Quickstart section you should have a file for your user .alice.yaml. For the purposes of this example let's also create a second user .carol.yaml.
1
meeco users:create -p supersecretpassword > .carol.yaml
Copied!
The next thing you are going to want to do is create the organization. Create a file called .organization-config.yaml with the content something like the following.
1
kind: Organization
2
metadata:
3
spec:
4
  name: SuperData Inc.
5
  description: My super data handling organization
6
  url: https://superdata.example.com
7
  email: [email protected]
Copied!
Then run the following command
1
meeco organizations:create -a .alice.yaml -c .organization-config.yaml > .organization.yaml
Copied!
The output .organization.yaml file will look something like the following.
1
kind: Organization
2
metadata:
3
  privateKey: "-----BEGIN RSA PRIVATE KEY-----\r
4
    ...
5
    -----END RSA PRIVATE KEY-----\r\n"
6
  publicKey: "-----BEGIN PUBLIC KEY-----\r
7
    ...
8
    -----END PUBLIC KEY-----\r\n"
9
spec:
10
  id: cc656956-6fb3-4bd1-a906-81c85dd6cb7e
11
  name: SuperData Inc.
12
  description: My super data handling organization
13
  url: https://superdata.example.com
14
  email: [email protected]
15
  status: requested
16
  requestor_id: 33bd39f9-980f-4ea6-92d3-6a28a218e6ac
17
  validated_by_id: null
18
  agent_id: null
19
  validated_at: null
20
  created_at: 2020-10-29T03:12:18.153Z
Copied!
Notice how the status field is set to requested at this stage, this means our team has been notified of your intent to create the organization and will review and get in contact with you via the email provided. At this stage only you and the team at Meeco can see the organization. You can check organization was created and in requested state waiting for approval with the following command.
1
meeco organizations:list -m requested -a .alice.yaml
Copied!
Once your organization has been approved by the team at meeco we'll let you know via email. From this point on your organization is publicly viewable via the API in Meeco. After that you can check to see that your organization is listed with the other publicly viewable organizations with this command.
1
meeco organizations:list -a .alice.yaml
Copied!
Which outputs like the following.
1
kind: Organizations
2
spec:
3
  - id: cc656956-6fb3-4bd1-a906-81c85dd6cb7e
4
    name: SuperData Inc.
5
    description: My super data handling organization
6
    url: https://superdata.example.com
7
    email: [email protected]
8
    status: validated
9
    requestor_id: 33bd39f9-980f-4ea6-92d3-6a28a218e6ac
10
    validated_by_id: 33bd39f9-980f-4ea6-92d3-6a28a218e6ac
11
    agent_id: 79b75bec-aafa-4850-9c47-dfce2c633453
12
    validated_at: 2020-10-29T05:40:22.991Z
13
    created_at: 2020-10-29T03:12:18.153Z
14
  ...
Copied!
To start adding members to your organization you must first authenticate as the organization.
1
meeco organizations:login -o .organization.yaml -a .alice.yaml > .organization-auth.yaml
Copied!
Next we have to create an invitation to become a member of the organization as the organization.
1
meeco organization-members:create-invitation -o .organization.yaml -a .organization-auth.yaml > .org-invitation.yaml
Copied!
Next lets have user Carol accept this invitation to become a member of the organization.
1
meeco organization-members:accept-invitation -i .org-invitation.yaml -a .carol.yaml > .carol-org-membership.yaml
Copied!
You can see the list of members in the organization with the command.
1
meeco organization-members:list -a .alice.yaml cc656956-6fb3-4bd1-a906-81c85dd6cb7e
2
# meeco organization-members:list -a <USER_AUTH_YAML> <ORGANIZATION_ID>
Copied!
Organization Services
Organization Services are what your organization can use to connect to users, share data with them, and have data shared back with you. These services are a set of credentials that you can put into your third party systems to give them access to meeco's services. For the purposes of this guide we will complete everything using the CLI however we recommend you set up an application which performs these tasks either using the @meeco/sdk npm package or hitting our API endpoints directly using the SDK as a guide.
First lets create a service configuration file .organization-service-config.yaml something like the following. (Hint: you can use the cryppo cli https://github.com/Meeco/cryppo-cli to quickly and easily create a keypair with the command cryppo genkeypair -p private.pem -P public.pem).
1
kind: OrganizationService
2
spec:
3
  name: Data Sharing Service
4
  description: This service is for outgoing shared data from application X
5
  contract: A message about the contract
Copied!
Next we create the service using that config file.
1
meeco organization-services:create -a .alice.yaml -c .organization-service-config.yaml cc656956-6fb3-4bd1-a906-81c85dd6cb7e > .organization-service.yaml
2
# meeco organization-services:create -a <USER_AUTH_YAML> -c <ORGANIZATION_SERVICE_CONFIG_FILE> <ORGANIZATION_ID> > <OUTPUT_FILE>
Copied!
The .organization-service.yaml should have output like the following.
1
kind: OrganizationService
2
metadata:
3
  privateKey: "-----BEGIN RSA PRIVATE KEY-----\r
4
    ...
5
    -----END RSA PRIVATE KEY-----\r\n"
6
  publicKey: "-----BEGIN PUBLIC KEY-----\r
7
    ...
8
    -----END PUBLIC KEY-----\r\n"
9
spec:
10
  id: c213d93e-32a5-4e1d-96bb-0816e7eb6c74
11
  name: Data Sharing Service
12
  description: This service is for outgoing shared data from application X
13
  contract: A message about the contract
14
  status: requested
15
  organization_id: cc656956-6fb3-4bd1-a906-81c85dd6cb7e
16
  validated_by_id: null
17
  agent_id: null
18
  validated_at: null
19
  created_at: 2020-11-03T03:43:03.751Z
Copied!
At this stage the Organization service has been requested and has the status requested. The metadata.privateKey here should be saved as configuration for your organization service application.
Before the validation of the organization service you can check on the pending services by running the command.
1
meeco organization-services:list -a .alice.yaml cc656956-6fb3-4bd1-a906-81c85dd6cb7e
2
# meeco organization-services:list -a .alice.yaml <ORGANIZATION_ID>
Copied!
You should see some output like the following.
1
kind: OrganizationServices
2
spec:
3
  - id: c213d93e-32a5-4e1d-96bb-0816e7eb6c74
4
    name: Data Sharing Service
5
    description: This service is for outgoing shared data from application X
6
    contract: null
7
    status: requested
8
    organization_id: cc656956-6fb3-4bd1-a906-81c85dd6cb7e
9
    validated_by_id: null
10
    agent_id: null
11
    validated_at: null
12
    created_at: 2021-05-10T06:14:18.968Z
Copied!
The meeco Team will again review this OrganizationService, reach out to you via email if needed, and validate your service. Once this is done we will notify you via email and you will be able to confirm that the organization service is now validated with the command.
1
meeco organization-services:get -a .alice.yaml cc656956-6fb3-4bd1-a906-81c85dd6cb7e c213d93e-32a5-4e1d-96bb-0816e7eb6c74
2
# meeco organization-services:get -a .alice.yaml <ORGANIZATION_ID> <SERVICE_ID>
Copied!
The result should be something like the following, if the service is not found (404) it means the service has not been validated yet.
1
kind: OrganizationService
2
spec:
3
  id: c213d93e-32a5-4e1d-96bb-0816e7eb6c74
4
  name: Data Sharing Service
5
  description: This service is for outgoing shared data from application X
6
  contract: A message about the contract
7
  status: validated
8
  organization_id: cc656956-6fb3-4bd1-a906-81c85dd6cb7e
9
  validated_by_id: 33bd39f9-980f-4ea6-92d3-6a28a218e6ac
10
  agent_id: 3392a0e4-0046-40d5-a532-5bca94f1d801
11
  validated_at: 2020-11-03T04:51:59.724Z
12
  created_at: 2020-11-03T04:27:16.784Z
Copied!
Now we have created our organization service we can request an authentication token for it. (NOTE: your organization service will need to be validated before you can login as it)
1
meeco organization-services:login -a .alice.yaml -s .organization-service.yaml > .organization-service-auth.yaml
Copied!
The .organization-service-auth.yaml should look like the following.
1
kind: Authentication
2
metadata:
3
  vault_access_token: ANDJk1gJpFKmwrCjNyd7
4
spec: {}
Copied!
The metadata.vault_access_token should be saved as configuration for your organization service application. So from now your application has a vault_access_token and a private_key, these should be set as configuration variables. But how do we use them.
Connecting your Organization to Users
Your organization first needs to connect to a user through it's organization service. To do that it will first create an invitation.
The keypair_external_id can be left blank in this case if we are using the same public key to connect with all users. In some cases you may wish to use a unique public key for each user connection, in this case you should store the related private key somewhere with reference to the user who you are connecting to.
The encrypted_recipient_name is a record to be used by your organization only, it should identify in some way who the invitation has been created for. It should encrypted and serialized using a Cryppo serialization format (see https://github.com/Meeco/cryppo-js for more details).
The public_key here can be unique per connection but in this case we are just going th use the keypair from the organization service.
The Authorization header here should be the vault_access_token from the .organization-service-auth.yaml from above. To convert the public_key into the format needed for betlow you can use yq (https://mikefarah.gitbook.io/yq/) like so cat .organization-service.yaml | yq -j eval.
1
# first part here just writes the json to a file removing all whitespace and newlines
2
cat <<'EOF' |  tr -d '\n' | tr -s ' ' > data.json
3
  {
4
    "public_key": {
5
      "keypair_external_id": "string",
6
      "public_key": "-----BEGIN PUBLIC KEY-----\rMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAzao4lCviLTEg2ze8jmts\ry6iG6iKX3TGIdlcHJbFBAs0oCVp29jhlOXVfwuxX6gqplLT44rpSnYcsvKYao7ol\rt7ZadkQg/j1xm+Sw/FTyLKhNyHznclnTUXPnnvY6sHwpfaC0NBIAy1XRI8r3gqiu\rngOx4afC+PeZnrCvhjsnmR1cd/FXTWQuH8GfrqdDbH3K8ObAv4r3VT2RcUvgUEVg\r6Yg29fAF5B9Wmcwl9Kr53nryp04412QvNjlJZlilbNsmvXYnPfu4bM8kRV56iBeE\rL1OOBu65oZcBvXym3Gtd057J+0kDqGp4t76qB9DNy8n3SikvY8hyZHQsx54QBecy\rKxPETEGVWGMFHI5+UIriMr0PEF4AUE9KZWVt3bAhQPyby3Fm9dju01q9nV2qt5Cy\rZnsNui2VZ7EGDxoJPH74fsnrXX7cX8VPFgg2pxmpzmI12X1YBKdymKvCRsa+5I5S\rF2/g5pwJznx1babFSCSenmPr8eIz6Y1iJSigwr4tsUAbE1C6Vn6PEBrsmzMFhe3M\rA7YwqJvNjOZZb3Yocaf08Xn8/oISCd1ItU5W6mLW/uwRSB4cGs/D7E5mNj0bvE+1\rG94RFHSDCzIYyPtb/8dFKlwSJ3Jm2HytiN7c2dVv61KrQFRyktPHPLVR/V6r8XcB\rFR6qZSfofTNCs7HI+VAIKV8CAwEAAQ==\r-----END PUBLIC KEY-----\r\n"
7
    },
8
    "invitation": {
9
      "encrypted_recipient_name": "Aes256Gcm.faHlODQ4Q3i11r6H-A8=.QUAAAAAFaXYADAAAAAD_GSnEC8ep0yiX7HYFYXQAEAAAAADUbHZ-1Bg6ZqmZkmo3t7JlAmFkAAUAAABub25lAAA="
10
    }
11
  }
12
EOF
13
# second part here actually makes the request
14
curl -X POST "https://sandbox.meeco.me/vault/invitations" \
15
  -d @data.json \
16
  -H "Accept: application/json" \
17
  -H "Meeco-Subscription-Key: Q7dFWQDGSsAE6tUo1G93Mlhn4SCOBrJe" \
18
  -H "Authorization: ANDJk1gJpFKmwrCjNyd7" \
19
  -H "Content-Type: application/json" \
20
  | json_pp \
21
  > invitation.json
Copied!
The invitation.json file should have output that looks something like.
1
{
2
   "invitation" : {
3
      "keypair_external_id" : "string",
4
      "token" : "cPWV4CwpWTHxhqaJGG9MRkVWxKojGhMPGs4oTuoBdTU",
5
      "message" : null,
6
      "user_image" : null,
7
      "integration_data" : {
8
         "organization_id" : "cc656956-6fb3-4bd1-a906-81c85dd6cb7e",
9
         "intent" : "service",
10
         "service_id" : "c213d93e-32a5-4e1d-96bb-0816e7eb6c74"
11
      },
12
      "id" : "62b54a86-66db-4e88-8e3d-3ce4457a2e97",
13
      "user_name" : null,
14
      "invited_user_id" : null,
15
      "outgoing" : true,
16
      "encrypted_recipient_name" : "Aes256Gcm.faHlODQ4Q3i11r6H-A8=.QUAAAAAFaXYADAAAAAD_GSnEC8ep0yiX7HYFYXQAEAAAAADUbHZ-1Bg6ZqmZkmo3t7JlAmFkAAUAAABub25lAAA=",
17
      "sent_at" : null
18
   }
19
}
Copied!
The invitation has been created so lets make an unrelated user to accept this connection invitation.
1
meeco users:create -p supersecretpassword > .dave.yaml
Copied!
Then for dave to accept this invitaion (and create the connection).
We should have a new keypair and public_key somewhere that we can use for this connection for Dave, dave might use the meeco keystore to manage this but in this case lets forget about the keystore for now to keep it simple.
Again the keypair_external_id would be a reference for Dave to retrieve the appropriate keypair (when using the keystore this would be the id of the key record) but we can just put the name of the organization service in there for this reference.
The invitation_token here would be .invitation.token from the invitation.json file.
The Authorization here should be Dave's authorization token (from .dave.yaml).
1
# first part here just writes the json to a file removing all whitespace and newlines
2
cat <<'EOF' |  tr -d '\n' | tr -s ' ' > data.json
3
  {
4
    "public_key": {
5
      "keypair_external_id": "DataSharingService",
6
      "public_key": "-----BEGIN PUBLIC KEY-----\nMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAqMILz56KuEsGlsEpML3h\nPN7OUf7HrLTtWkazwbNIkK3RLWtNI5X8bd0ISUuwgXQVzZuWyC6wXPiWSDwXILAf\nJPusVT6Kh0EmXhJtBRCkF64fXKz54rI/2kYpuP4HZbNStj8OIRv/ECV7glDf+4Yq\nWDdLmh2vHDHF7bIRQnuWwV3ZL10Gkuh671aJkkVRdApUZUNcDfz1VK/SDMLxuxMg\n8D78u+d0WgThXzEwlcHtRitLA4QekNjVNPkoZoRIJSWLWqwkaOd0+YAhPNso3t9Y\nwaLT0/hDe4qBRuWpkoCIIUxE1JPuUbv3ePwsvyX9ksKNwQ6zVyOBXJwjspjac3mS\nH2DXS8dwU/ObKI3v9c/aY0i4iV6xJIkDxV2V8HclMOm1cLmgoc9YMU9YuM2LZ1GX\n707XBrdRD1v/FNQa/HJjFSapXcztN03etswrJcYFxVxDWZ84uMO2TNHOsSbOgop9\nmF5hRLQ+PT45v+mNNmbJa62yRaVkIV4VvsHgBVsz6TWsZGxu+IsNLKT/OYju/zzn\nvQSig5Ue7BAZqMOlibWiB6gX8vM336okrOWASnvWZNe+a7QpQdYYbHbH/leFZFCA\nht20DXUHLXYAKk9gvdqKycYnVsaRb2dnaSdUez+AUsIme0gWPscwSf3XpARUDc5i\nEKfIKQZzxyj4Y7W6eGwAfCMCAwEAAQ==\n-----END PUBLIC KEY-----\n"
7
    },
8
    "connection": {
9
      "encrypted_recipient_name": "Aes256Gcm.eDfbJAx9qhRZvjy1NnE=.QUAAAAAFaXYADAAAAAAPXFAVfuk4dKCl4VEFYXQAEAAAAACIVxZUFNld30Dy39K-DeZKAmFkAAUAAABub25lAAA=",
10
      "invitation_token": "cPWV4CwpWTHxhqaJGG9MRkVWxKojGhMPGs4oTuoBdTU"
11
    }
12
  }
13
EOF
14
# second part here actually makes the request
15
curl -X POST "https://sandbox.meeco.me/vault/connections" \
16
  -d @data.json \
17
  -H "Accept: application/json" \
18
  -H "Meeco-Subscription-Key: Q7dFWQDGSsAE6tUo1G93Mlhn4SCOBrJe" \
19
  -H "Authorization: hZwx4XPj6MZJcPHPKHqc" \
20
  -H "Content-Type: application/json" \
21
  | json_pp \
22
  > connection.json
Copied!
The connection will have been created and the output in connection.json will look something like.
1
{
2
   "connection" : {
3
      "own" : {
4
         "connection_type" : "service",
5
         "integration_data" : {
6
            "intent" : "service",
7
            "service_id" : "c213d93e-32a5-4e1d-96bb-0816e7eb6c74",
8
            "organization_id" : "cc656956-6fb3-4bd1-a906-81c85dd6cb7e"
9
         },
10
         "user_id" : "d62d37f8-9f53-4be2-9df3-af7541d08316",
11
         "id" : "c76b28f6-ab27-4b41-a8db-3184d17b8fbc",
12
         "user_public_key" : "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----\n",
13
         "user_type" : "human",
14
         "user_keypair_external_id" : "DataSharingService",
15
         "encrypted_recipient_name" : "Aes256Gcm.eDfbJAx9qhRZvjy1NnE=.QUAAAAAFaXYADAAAAAAPXFAVfuk4dKCl4VEFYXQAEAAAAACIVxZUFNld30Dy39K-DeZKAmFkAAUAAABub25lAAA="
16
      },
17
      "the_other_user" : {
18
         "connection_type" : "service",
19
         "id" : "359486bb-e998-4699-9eed-5e7194987565",
20
         "user_id" : "c3482646-f6cf-48a2-877c-04857802d4de",
21
         "integration_data" : {
22
            "organization_id" : "cc656956-6fb3-4bd1-a906-81c85dd6cb7e",
23
            "service_id" : "c213d93e-32a5-4e1d-96bb-0816e7eb6c74",
24
            "intent" : "service"
25
         },
26
         "user_keypair_external_id" : "string",
27
         "user_type" : "service_agent",
28
         "user_public_key" : "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----\n",
29
      }
30
   }
31
}
Copied!
The OrganizationService has now made it's first connection with a user.
Guides - Previous
Attachments
Next - Guides
On-sharing & Client Tasks
Last modified 5mo ago
Copy link
Contents
Overview
Setting up an Organization
Organization Services
Connecting your Organization to Users