DataTrails

Tenancies API

Tenancies 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.

Tenancies API Examples

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

Retrieve the Current List of Administrators

To fetch the list of Administrators, simply GET the tenancies/root_principals resource:

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

Update the List of Administrators

Define the update parameters and store in /path/to/jsonfile:

{
   "administrators": [
       {
           "issuer": "https://login.microsoftonline.com/5c129635-5858-4fe3-9bef-444f6c7ee1cf/v2.0",
           "subject": "58589bef-4fe3-9a3b-23df-8527bc45e1cf",
           "display_name": "Jane Smith",
           "email":  "jane.smith@synsation.org"
       },
       {
           "issuer": "https://login.microsoftonline.com/5c129635-5858-4fe3-9bef-444f6c7ee1cf/v2.0",
           "subject": "27bc5b4f-9a3b-4fe3-23df-e1c7bc45e1cf",
           "display_name": "Nate Rogers",
           "email":  "nate.rogers@synsation.org"
       }
    ]
}

Update the Administrators by PATCHing the tenancies/root_principals resource:

curl -v -X PATCH \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.datatrails.ai/archivist/v1/tenancies/root_principals

Tenancies OpenAPI Docs

API to manage tenancies

get  /archivist/v1/tenancies/archivist/v1/tenancies/root_principals

Fetch the current list of tenant root user principals

Description: Fetch the current list of tenant root user principals.

{
  "root_principals": [
    {
      "display_name": "Bob Smith",
      "email": "bob@job",
      "issuer": "job.idp.server/1234",
      "subject": "08838336-c357-460d-902a-3aba9528dd22"
    }
  ]
}
Response ParameterTypeDescription
root_principalsarrayThe principal description assured by the configured Identity Provider. All values are according to OIDC id token claims and standard claims. See https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to update the root principals.

patch  /archivist/v1/tenancies/archivist/v1/tenancies/root_principals

Update the list of tenant root user principals

Description: Replace the list of tenant root user principals. Note that you are not able to remove yourself from the list.

{
  "root_principals": [
    {
      "display_name": "Bob Smith",
      "email": "bob@job",
      "issuer": "job.idp.server/1234",
      "subject": "08838336-c357-460d-902a-3aba9528dd22"
    }
  ]
}
ParameterTypeDescription
root_principalsarrayThe principal description assured by the configured Identity Provider. All values are according to OIDC id token claims and standard claims. See https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims

{
  "root_principals": [
    {
      "display_name": "Bob Smith",
      "email": "bob@job",
      "issuer": "job.idp.server/1234",
      "subject": "08838336-c357-460d-902a-3aba9528dd22"
    }
  ]
}
Response ParameterTypeDescription
root_principalsarrayThe principal description assured by the configured Identity Provider. All values are according to OIDC id token claims and standard claims. See https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
ResponsesDescription
200A successful response.
400Returned when the request is badly formed. Including, but not limited to, attempting to remove yourself as a root uesr principal.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to update the root principals.

get  /archivist/v1/tenancies/archivist/v1/tenancies/self

Get tenant record

Description: Returns an administrator’s view of tenant for which they’re authenticated

{
  "display_name": "My First Tenancy",
  "identity": "tenant/08838336-c357-460d-902a-3aba9528dd22",
  "verified_domain": "foo.com"
}
Response ParameterTypeDescription
display_namestringCustomer friendly name for the tenant.
enterprise_sso_config
enterprise_sso_enabledboolean
identitystringtenant identity {UUID}
verified_domainstring
ResponsesDescription
200A successful response.
400Supplied parameters were invalid
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to retrieve the tenant id.

patch  /archivist/v1/tenancies/archivist/v1/tenancies/self

Update tenant record

Description: Enables a root principal of the tenant to update the tenant record.

{
  "display_name": "My First Tenancy",
  "identity": "tenant/08838336-c357-460d-902a-3aba9528dd22",
  "verified_domain": "foo.com"
}
Response ParameterTypeDescription
display_namestringCustomer friendly name for the tenant.
enterprise_sso_config
enterprise_sso_enabledboolean
identitystringtenant identity {UUID}
verified_domainstring
ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to perform this action.
404Returned when the referenced tenant does not exist.

get  /archivist/v1/tenancies/archivist/v1/tenancies/users

List Users

Description: Returns a list of Users active in or invited to the tenant.

{
  "page_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InN0dW50aWR",
  "users": [
    {
      "email": "frank123@example.com",
      "identity": "users/87d349ed-44d7-43e1-9a83-5f2406dee5bd",
      "issuer": "frank@example.com",
      "subject": "franky123",
      "user_status": "ACTIVE"
    }
  ]
}
Response ParameterTypeDescription
next_page_tokenstringToken to retrieve the next page of results or empty if there are none.
usersarrayUser Data
ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to read the users.
404Returned when the identified users don’t exist.
500Returned when the underlying storage system returns an error.

delete  /archivist/v1/tenancies/archivist/v1/tenancies/users/{user_uuid}

Deletes User

Description: Deletes a User from the tenancy.

{
  "email": "frank123@example.com",
  "identity": "users/87d349ed-44d7-43e1-9a83-5f2406dee5bd",
  "issuer": "frank@example.com",
  "subject": "franky123",
  "user_status": "ACTIVE"
}
Response ParameterTypeDescription
displayNamestringdisplay name for the user
emailstringUser email.
identitystringuser identity {UUID}
issuerstringoptional issuer of the principal identity. Where the issuer is not provided the subject is treated as a free string
subjectstringunique identifier of the principal (within issuer context)
ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to read the user.
500Returned when the underlying storage system returns an error.

get  /archivist/v1/tenancies/archivist/v1/tenancies/{uuid}:publicinfo

Public Tenant Information.

Description: Return the publically avaialble tenant information.

{
  "identity": "tenant/add30235-1424-4fda-840a-d5ef82c4c96f",
  "verified_domain": "exampleltd"
}
Response ParameterTypeDescription
identitystring
verified_domainstring
ResponsesDescription
200A successful response.

Simple API for User Management

get  /archivist/v1/users/archivist/v1/users/tenants

List User Tenants

Description: Returns a list of tenancies the user has access to.

{
  "page_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InN0dW50aWR",
  "tenants": [
    {
      "display_name": "Bobs Tenancy",
      "identity": "tenant/01038663-c357-470d-912a-3abc9528dd21"
    },
    {
      "display_name": "Alices Tenancy",
      "identity": "tenant/12149552-f258-430d-922b-4bcd8413ee30"
    }
  ]
}
Response ParameterTypeDescription
next_page_tokenstringToken to retrieve the next page of results or empty if there are none.
tenantsarrayTenant information for a user.
ResponsesDescription
200A successful response.
400Returned when the request is badly formed.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to read the user.
404Returned when the identified user don’t exist.
500Returned when the underlying storage system returns an error.

← Public Assets API
YAML Runner Components →