RKVST

Tenancies API

Tenancies API Reference

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 Root Principals

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

curl -v -X GET \
     -H "@$BEARER_TOKEN_FILE" \
     https://app.rkvst.io/archivist/v1/tenancies/root_principals

Update the List of Root Principals

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

{
   "root_principals": [
       {
           "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 root principals by PATCHing the tenancies/root_principals resource:

curl -v -X PATCH \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    -d "@/path/to/jsonfile" \
    https://app.rkvst.io/archivist/v1/tenancies/root_principals

Tenancies OpenAPI Docs

Simple API for User Management

get  /archivist/v1/tenancies/invitetokenhint

Create an invite token

Description: Internal api to allow creation of invite token.

null
Response ParameterTypeDescription
expiry_timestringinvite expiry time
tokenstring
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.
defaultAn unexpected error response.

get  /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.
defaultAn unexpected error response.

patch  /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.
defaultAn unexpected error response.

get  /archivist/v1/tenancies/tenantid

Get ID of tenant associated with issuer and/or subject, and create if not exists.

Description: Get ID of tenant associated with issuer and/or subject, and create if not exists.

null
Response ParameterTypeDescription
identitystringtenant identity {UUID}
new_tenantbooleantrue if this request created a new tenant
tiertenant tier FREE or PREMIUM
ResponsesDescription
200A successful response.
400Returned when the user doesn’t provide an issuer or subject to filter on.
401Returned when the user is not authenticated to the system.
403Returned when the user is not authorized to retrieve the tenant id.
defaultAn unexpected error response.

get  /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.
defaultAn unexpected error response.

delete  /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.
defaultAn unexpected error response.

get  /archivist/v1/tenancies:openapi

Get OpenAPI spec for Tenancies

Description: Get OpenAPI v2.0 spec for Tenancies

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/v1/tenancies:openapi-ui

Get OpenAPI UI for Tenancies

Description: Get OpenAPI v2.0 UI for Tenancies

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/v1/users/tenants

List User Tenants

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

{
  "page_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InN0dW50aWR",
  "tenants": [
    "tenancies/01038663-c357-470d-912a-3abc9528dd21",
    "tenancies/12147552-d466-381c-805b-4cbd1018ef30"
  ]
}
Response ParameterTypeDescription
next_page_tokenstringToken to retrieve the next page of results or empty if there are none.
tenantsarraytenants in the form tenancies/{UUID}
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.
defaultAn unexpected error response.

Edit this page on GitHub

← System API
TLS CA Certificates API →