IAM Subjects API

IAM Subjects 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.

IAM Subjects API Examples

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

IAM Subjects Creation

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

{
    "display_name": "Some description",
    "wallet_pub_key": ["key1"],
    "tessera_pub_key": ["key2"]
}

Note: The values for wallet_pub_key and tessera_pub_key are found by decoding the Subject string that is provided by the Tenancy Administrator of the other organization. See the JSON tab here for more detail.

Create the IAM Subject:

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

The response is:

{
    "identity": "subjects/3f5be24f-fd1b-40e2-af35-ec7c14c74d53",
    "display_name": "Some description",
    "wallet_pub_key": ["key1"],
    "wallet_address": ["address"],
    "tessera_pub_key": ["key2"]
}

IAM Subjects Retrieval

IAM Subject records in DataTrails are tokenized at creation time and referred to in all API calls and smart contracts throughout the system by a unique identity of the form:

subjects/12345678-90ab-cdef-1234-567890abcdef

If you do not know the Subjects’s identity you can fetch IAM Subject records using other information you do know, such as the Subject’s name.

Fetch all IAM Subjects (v1)

To fetch all IAM Subjects records, simply GET the /subjects resource:

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

Fetch specific IAM Subject by identity (v1)

If you know the unique identity of the IAM Subject record simply GET the resource:

curl -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     https://app.datatrails.ai/archivist/iam/v1/subjects/6a951b62-0a26-4c22-a886-1082297b063b

Fetch IAM Subjects by Name (v1)

To fetch all IAM subjects with a specific name, GET the /subjects resource and filter on display_name:

curl -g -v -X GET \
     -H "@$HOME/.datatrails/bearer-token.txt" \
     "https://app.datatrails.ai/archivist/iam/v1/subjects?display_name=Acme"

Each of these calls returns a list of matching IAM Subjects records in the form:

{
    "subjects": [
        {
            "identity": "subjects/6a951b62-0a26-4c22-a886-1082297b063b",
            "display_name": "Some description",
            "wallet_pub_key": ["key1"],
            "wallet_address": ["address1"],
            "tessera_pub_key": ["key2"]
        },
        {
            "identity": "subjects/12345678-0a26-4c22-a886-1082297b063b",
            "display_name": "Some other description",
            "wallet_pub_key": ["key5"],
            "wallet_address": ["address5"],
            "tessera_pub_key": ["key7"]
        }
    ]
}

IAM Subject Deletion

To delete an IAM Subject, issue the following request:

curl -v -X DELETE \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    https://app.datatrails.ai/archivist/iam/v1/subjects/47b58286-ff0f-11e9-8f0b-362b9e155667

The response is {}.

IAM Subject Update

Define the Subject parameters to be changed and store in /path/to/jsonfile:

{
    "wallet_pub_key": ["key1"],
    "tessera_pub_key": ["key2"]
}

Update the IAM Subject:

curl -v -X PATCH \
    -H "@$HOME/.datatrails/bearer-token.txt" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.datatrails.ai/archivist/iam/v1/subjects/47b58286-ff0f-11e9-8f0b-362b9e155667

The response is:

{
    "identity": "subjects/3f5be24f-fd1b-40e2-af35-ec7c14c74d53",
    "display_name": "Some description",
    "wallet_pub_key": ["key1"],
    "wallet_address": ["address1"],
    "tessera_pub_key": ["key3"]
}

IAM Subject Self Entry

There is an immutable entry in the Subjects API called Self that contains the keys for the hosting organization of the DataTrails Tenant.

This entry cannot be deleted or updated.

This special identity is:

subjects/00000000-0000-0000-0000-000000000000

Fetch Self IAM Subject by Identity (v1)

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

The response is:

[
    {
        "identity": "subjects/00000000-0000-0000-0000-000000000000",
        "display_name": "Some description",
        "wallet_pub_key": ["key1"],
        "wallet_address": ["address1"],
        "tessera_pub_key": ["key3"]
    }
]

IAM Subjects OpenAPI Docs

API to manage Identity Access Management Subjects.

get /archivist/iam/v1/subjects

List subjects

Description: Returns a paginated list of subjects

{
  "page_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InN0dW50aWR",
  "subjects": [
    {
      "confirmation_status": "PENDING",
      "display_name": "Some description",
      "identity": "subjects/08838336-c357-460d-902a-3aba9528dd22",
      "tessera_pub_key": [
        "key3"
      ],
      "wallet_pub_key": [
        "key1"
      ]
    }
  ]
}

Response Parameter	Type	Description
next_page_token	string	Token to retrieve the next page of results or empty if there are none.
subjects	array	Describes Organization including wallet addresses and public keys used to create assets and events.

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 subject.
429	Returned when a user exceeds their subscription’s rate limit for requests.
500	Returned when the underlying storage system returns an error.

post /archivist/iam/v1/subjects

Create an subject

Description: This request creates a new subject. The display_name is the friendly name.

{
  "display_name": "Some description",
  "tessera_pub_key": [
    "key3"
  ],
  "wallet_pub_key": [
    "key1"
  ]
}

Parameter	Type	Description
display_name	string	Customer friendly name for the subject.
tessera_pub_key	array	Organisation’s tessara wallet keys (BNF)
wallet_pub_key	array	Organisation’s public wallet keys (BNF)

{
  "confirmation_status": "PENDING",
  "display_name": "Some description",
  "identity": "subjects/08838336-c357-460d-902a-3aba9528dd22",
  "tessera_pub_key": [
    "key3"
  ],
  "wallet_address": [
    "address1"
  ],
  "wallet_pub_key": [
    "key1"
  ]
}

Response Parameter	Type	Description
confirmation_status
display_name	string	Customer friendly name for the subject.
identity	string	Unique identification for the subject, Relative Resource Name
tenant	string	Tenent id
tessera_pub_key	array	Organisation’s tessara wallet keys (BNF)
wallet_address	array	Organisation’s wallet addresses
wallet_pub_key	array	Organisation’s public wallet keys (BNF)

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 create a subject.
429	Returned when a user exceeds their subscription’s rate limit for requests.
500	Returned when the underlying storage system returns an error.

delete /archivist/iam/v1/subjects/{uuid}

Delete a subject

Description: Delete the identified subject

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 delete the subject.
404	Returned when the identified laccess policy does not exist.
429	Returned when a user exceeds their subscription’s rate limit for requests.
500	Returned when the underlying storage system returns an error.

get /archivist/iam/v1/subjects/{uuid}

Get an subject

Description: Returns the identified subject

{
  "confirmation_status": "PENDING",
  "display_name": "Some description",
  "identity": "subjects/08838336-c357-460d-902a-3aba9528dd22",
  "tessera_pub_key": [
    "key3"
  ],
  "wallet_address": [
    "address1"
  ],
  "wallet_pub_key": [
    "key1"
  ]
}

Response Parameter	Type	Description
confirmation_status
display_name	string	Customer friendly name for the subject.
identity	string	Unique identification for the subject, Relative Resource Name
tenant	string	Tenent id
tessera_pub_key	array	Organisation’s tessara wallet keys (BNF)
wallet_address	array	Organisation’s wallet addresses
wallet_pub_key	array	Organisation’s public wallet keys (BNF)

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 subject.
404	Returned when the identified subject does not exist.
429	Returned when a user exceeds their subscription’s rate limit for requests.
500	Returned when the underlying storage system returns an error.

patch /archivist/iam/v1/subjects/{uuid}

Update a subject's details

Description: Perform a full or partial update of the identified subject

{
  "confirmation_status": "PENDING",
  "display_name": "Some description",
  "identity": "subjects/08838336-c357-460d-902a-3aba9528dd22",
  "tessera_pub_key": [
    "key3"
  ],
  "wallet_address": [
    "address1"
  ],
  "wallet_pub_key": [
    "key1"
  ]
}

Response Parameter	Type	Description
confirmation_status
display_name	string	Customer friendly name for the subject.
identity	string	Unique identification for the subject, Relative Resource Name
tenant	string	Tenent id
tessera_pub_key	array	Organisation’s tessara wallet keys (BNF)
wallet_address	array	Organisation’s wallet addresses
wallet_pub_key	array	Organisation’s public wallet keys (BNF)

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 update the subject.
404	Returned when the identified subject does not exist.
429	Returned when a user exceeds their subscription’s rate limit for requests.
500	Returned when the underlying storage system returns an error.

IAM Subjects API

IAM Subjects API Examples#

IAM Subjects Creation#

IAM Subjects Retrieval#

Fetch all IAM Subjects (v1)#

Fetch specific IAM Subject by identity (v1)#

Fetch IAM Subjects by Name (v1)#

IAM Subject Deletion#

IAM Subject Update#

IAM Subject Self Entry#

Fetch Self IAM Subject by Identity (v1)#

IAM Subjects OpenAPI Docs#

get /archivist/iam/v1/subjects

get /archivist/iam/v1/subjects

List subjects

Example Response

post /archivist/iam/v1/subjects

post /archivist/iam/v1/subjects

Create an subject

Example Request

Example Response

delete /archivist/iam/v1/subjects/{uuid}

delete /archivist/iam/v1/subjects/{uuid}

Delete a subject

get /archivist/iam/v1/subjects/{uuid}

get /archivist/iam/v1/subjects/{uuid}

Get an subject

Example Response

patch /archivist/iam/v1/subjects/{uuid}

patch /archivist/iam/v1/subjects/{uuid}

Update a subject's details

Example Response

IAM Subjects API Examples

IAM Subjects Creation

IAM Subjects Retrieval

Fetch all IAM Subjects (v1)

Fetch specific IAM Subject by identity (v1)

Fetch IAM Subjects by Name (v1)

IAM Subject Deletion

IAM Subject Update

IAM Subject Self Entry

Fetch Self IAM Subject by Identity (v1)

IAM Subjects OpenAPI Docs