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

get  /archivist/iam/v1/subjects

List subjects

Description: Returns a paginated list of subjects

{
  "page_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InN0dW50aWR",
  "subjects": [
    {
      "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 an Access Policy for OBAC
Responses Description
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.
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"
  ]
}
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)

{
  "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
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
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.
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

Responses Description
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.
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

{
  "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
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
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.
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

{
  "display_name": "Some description",
  "identity": "subjects/08838336-c357-460d-902a-3aba9528dd22",
  "tessera_pub_key": [
    "key3"
  ],
  "wallet_address": [
    "address1"
  ],
  "wallet_pub_key": [
    "key1"
  ]
}
Parameter Type Description
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)

{
  "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
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
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.
500Returned when the underlying storage system returns an error.
defaultAn unexpected error response.

Edit this page on GitHub