IAM Subjects API

IAM Subjects API Reference

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 subjects parameters and store in /path/to/jsonfile:

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

Create the IAM subject:

curl -v -X POST \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.rkvst.io/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 RKVST 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 "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/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 "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/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 "@$BEARER_TOKEN_FILE" \
     "https://app.rkvst.io/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 otherdescription",
            "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 "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    https://app.rkvst.io/archivist/iam/v1/subjects/47b58286-ff0f-11e9-8f0b-362b9e155667

The response is {}.

IAM Subject Update

Define the subjects 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 "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.rkvst.io/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 organisation of the RKVST 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 "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/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 ParameterTypeDescription
next_page_tokenstringToken to retrieve the next page of results or empty if there are none.
subjectsarrayDescribes Organization including wallet addresses and public keys used to create assets and events.
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 subject.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.
defaultAn unexpected error response.

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"
  ]
}
ParameterTypeDescription
display_namestringCustomer friendly name for the subject.
tessera_pub_keyarrayOrganisation’s tessara wallet keys (BNF)
wallet_pub_keyarrayOrganisation’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 ParameterTypeDescription
confirmation_status
display_namestringCustomer friendly name for the subject.
identitystringUnique identification for the subject, Relative Resource Name
tenantstringTenent id
tessera_pub_keyarrayOrganisation’s tessara wallet keys (BNF)
wallet_addressarrayOrganisation’s wallet addresses
wallet_pub_keyarrayOrganisation’s public wallet keys (BNF)
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 create a subject.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.
defaultAn unexpected error response.

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

Delete a subject

Description: Delete the identified subject

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

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 ParameterTypeDescription
confirmation_status
display_namestringCustomer friendly name for the subject.
identitystringUnique identification for the subject, Relative Resource Name
tenantstringTenent id
tessera_pub_keyarrayOrganisation’s tessara wallet keys (BNF)
wallet_addressarrayOrganisation’s wallet addresses
wallet_pub_keyarrayOrganisation’s public wallet keys (BNF)
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 subject.
404Returned when the identified subject does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.
defaultAn unexpected error response.

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 ParameterTypeDescription
confirmation_status
display_namestringCustomer friendly name for the subject.
identitystringUnique identification for the subject, Relative Resource Name
tenantstringTenent id
tessera_pub_keyarrayOrganisation’s tessara wallet keys (BNF)
wallet_addressarrayOrganisation’s wallet addresses
wallet_pub_keyarrayOrganisation’s public wallet keys (BNF)
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 update the subject.
404Returned when the identified subject does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.
defaultAn unexpected error response.

get  /archivist/iam/v1/subjects:openapi

Get OpenAPI spec for Subjects

Description: Get OpenAPI v2.0 spec for Subjects

ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

get  /archivist/iam/v1/subjects:openapi-ui

Get OpenAPI UI for Subjects

Description: Get OpenAPI v2.0 UI for Subjects

ResponsesDescription
200A successful response.
401Returned when the user is not authenticated to the system.
429Returned when a user exceeds their subscription’s rate limit for requests.
defaultAn unexpected error response.

Edit this page on GitHub