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 Parameter | Type | Description |
---|---|---|
root_principals | array | The 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 |
Responses | Description |
---|---|
200 | A successful response. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned 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"
}
]
}
Parameter | Type | Description |
---|---|---|
root_principals | array | The 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 Parameter | Type | Description |
---|---|---|
root_principals | array | The 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 |
Responses | Description |
---|---|
200 | A successful response. |
400 | Returned when the request is badly formed. Including, but not limited to, attempting to remove yourself as a root uesr principal. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned 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",
"enterprise_sso_config": {
"client_id": "foo",
"client_secret": "",
"config_url": "foo",
"issuer": "foo",
"policy_id": "foo"
},
"enterprise_sso_enabled": true,
"identity": "tenant/08838336-c357-460d-902a-3aba9528dd22",
"verified_domain": "foo.com"
}
Response Parameter | Type | Description |
---|---|---|
display_name | string | Customer friendly name for the tenant. |
enterprise_sso_config | ||
enterprise_sso_enabled | boolean | |
identity | string | tenant identity {UUID} |
verified_domain | string |
Responses | Description |
---|---|
200 | A successful response. |
400 | Supplied parameters were invalid |
401 | Returned when the user is not authenticated to the system. |
403 | Returned 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",
"enterprise_sso_config": {
"client_id": "foo",
"client_secret": "",
"config_url": "foo",
"issuer": "foo",
"policy_id": "foo"
},
"enterprise_sso_enabled": true,
"identity": "tenant/08838336-c357-460d-902a-3aba9528dd22",
"verified_domain": "foo.com"
}
Response Parameter | Type | Description |
---|---|---|
display_name | string | Customer friendly name for the tenant. |
enterprise_sso_config | ||
enterprise_sso_enabled | boolean | |
identity | string | tenant identity {UUID} |
verified_domain | string |
Responses | Description |
---|---|
200 | A successful response. |
400 | Returned when the request is badly formed. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to perform this action. |
404 | Returned 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 Parameter | Type | Description |
---|---|---|
next_page_token | string | Token to retrieve the next page of results or empty if there are none. |
users | array | User Data |
Responses | Description |
---|---|
200 | A successful response. |
400 | Returned when the request is badly formed. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to read the users. |
404 | Returned when the identified users don’t exist. |
500 | Returned 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 Parameter | Type | Description |
---|---|---|
displayName | string | display name for the user |
string | User email. | |
identity | string | user identity {UUID} |
issuer | string | optional issuer of the principal identity. Where the issuer is not provided the subject is treated as a free string |
subject | string | unique identifier of the principal (within issuer context) |
Responses | Description |
---|---|
200 | A successful response. |
400 | Returned when the request is badly formed. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to read the user. |
500 | Returned 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 Parameter | Type | Description |
---|---|---|
identity | string | |
verified_domain | string |
Responses | Description |
---|---|
200 | A 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 Parameter | Type | Description |
---|---|---|
next_page_token | string | Token to retrieve the next page of results or empty if there are none. |
tenants | array | Tenant information for a user. |
Responses | Description |
---|---|
200 | A successful response. |
400 | Returned when the request is badly formed. |
401 | Returned when the user is not authenticated to the system. |
403 | Returned when the user is not authorized to read the user. |
404 | Returned when the identified user don’t exist. |
500 | Returned when the underlying storage system returns an error. |