Members API

Members API Reference

Note: This page is primarily intended for developers who will be writing applications that will use DataTrails for provenance. If you are looking for a simple way to test our API you might prefer our Postman collection, the YAML runner or the Developers section of the web UI.

Additional YAML examples can be found in the articles in the Overview section.

Members API Examples#

Create the bearer_token and store in a file in a secure local directory with 0600 permissions.

Listing members of your tenant#

To fetch the list of members, simply GET the /members resource

curl -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/archivist/iam/v1/members

By default this doesn’t show members that are deactivated. You can filter the list to include deactivated users:

curl -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/archivist/iam/v1/members?member_state=MEMBER_STATE_BOTH

Promoting a user to ‘OWNER’ role in a tenancy#

You can manage the roles of a user (i.e. promoting or demoting them with the ‘OWNER’ role) by PATCHing their membership record. With the identity of the tenant member record corresponding to the user in question, submit this request to set their roles to a list containing only ‘OWNER’. To demote the member, simply send an empty list.

curl -v -X PATCH \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    -d "{'roles': ['OWNER']}" \
    https://app.datatrails.ai/archivist/iam/v1/{member_identity}

Deactivating a member of your tenant#

When a user should no longer have access to your tenant, you can deactivate them programatically using the following API call:

curl -v -X POST \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    https://app.datatrails.ai/archivist/iam/v1/{member_identity}:deactivate

and then re-activate them like so:

curl -v -X POST \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    https://app.datatrails.ai/archivist/iam/v1/{member_identity}:activate

User roles are stripped when a user is deactivated, so upon reactivation the user will only have basic user rights. If required once reactivated, follow the steps above to promote this user to ‘Owner’ role.

Members OpenAPI Docs#

{
  "members": [
    {
      "active": true,
      "display_name": "User One",
      "email": "user.one@datatrails.test",
      "identity": "members/08838336-c357-460d-902a-3aba9528dd22",
      "roles": [
        "OWNER"
      ]
    }
  ],
  "page_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InN0dW50aWR"
}

{
  "active": true,
  "display_name": "User One",
  "email": "user.one@datatrails.test",
  "identity": "members/08838336-c357-460d-902a-3aba9528dd22",
  "roles": [
    "OWNER"
  ]
}

{
  "active": true,
  "display_name": "User One",
  "email": "user.one@datatrails.test",
  "identity": "members/08838336-c357-460d-902a-3aba9528dd22",
  "roles": [
    "OWNER"
  ]
}

{
  "active": true,
  "display_name": "User One",
  "email": "user.one@datatrails.test",
  "identity": "members/08838336-c357-460d-902a-3aba9528dd22",
  "roles": [
    "OWNER"
  ]
}

{
  "memberships": [
    {
      "display_name": "Bobs Tenancy",
      "identity": "members/01234567-c357-470d-912a-3abc9528dd21",
      "tenant_id": "tenancies/01038663-c357-470d-912a-3abc9528dd21"
    },
    {
      "display_name": "Alices Tenancy",
      "identity": "members/76543210-c357-470d-912a-3abc9528dd21",
      "tenant_id": "tenancies/12149552-f258-430d-922b-4bcd8413ee30"
    }
  ],
  "page_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InN0dW50aWR"
}