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 Parameter	Type	Description
expiry_time	string	invite expiry time
token	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.
default	An 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 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.
default	An 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"
    }
  ]
}

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.
default	An unexpected error response.

patch /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",
  "identity": "tenant/08838336-c357-460d-902a-3aba9528dd22",
  "verified_domain": "foo.com"
}

Response Parameter	Type	Description
display_name	string	Customer friendly name for the tenant.
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.
default	An 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 Parameter	Type	Description
identity	string	tenant identity `{UUID}`
new_tenant	boolean	true if this request created a new tenant
tier		tenant tier FREE or PREMIUM

Responses	Description
200	A successful response.
400	Returned when the user doesn’t provide an issuer or subject to filter on.
401	Returned when the user is not authenticated to the system.
403	Returned when the user is not authorized to retrieve the tenant id.
default	An 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 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.
default	An 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 Parameter	Type	Description
displayName	string	display name for the user
email	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.
default	An unexpected error response.

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

get /archivist/v1/tenancies:openapi

Get OpenAPI spec for Tenancies

Description: Get OpenAPI v2.0 spec for Tenancies

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

get /archivist/v1/tenancies:openapi-ui

Get OpenAPI UI for Tenancies

Description: Get OpenAPI v2.0 UI for Tenancies

Responses	Description
200	A successful response.
401	Returned when the user is not authenticated to the system.
429	Returned when a user exceeds their subscription’s rate limit for requests.
default	An 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": [
    {
      "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.
default	An unexpected error response.

Edit this page on GitHub

Tenancies API

Tenancies API Examples#

Retrieve the Current List of Root Principals#

Update the List of Root Principals#

Tenancies OpenAPI Docs#

get /archivist/v1/tenancies/invitetokenhint

get /archivist/v1/tenancies/invitetokenhint

Create an invite token

Example Response

get /archivist/v1/tenancies/root_principals

get /archivist/v1/tenancies/root_principals

Fetch the current list of tenant root user principals

Example Response

patch /archivist/v1/tenancies/root_principals

patch /archivist/v1/tenancies/root_principals

Update the list of tenant root user principals

Example Request

Example Response

patch /archivist/v1/tenancies/self

patch /archivist/v1/tenancies/self

Update tenant record

Example Response

get /archivist/v1/tenancies/tenantid

get /archivist/v1/tenancies/tenantid

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

Example Response

get /archivist/v1/tenancies/users

get /archivist/v1/tenancies/users

List Users

Example Response

delete /archivist/v1/tenancies/users/{user_uuid}

delete /archivist/v1/tenancies/users/{user_uuid}

Deletes User

Example Response

get /archivist/v1/tenancies/{uuid}:publicinfo

get /archivist/v1/tenancies/{uuid}:publicinfo

Public Tenant Information.

Example Response

get /archivist/v1/tenancies:openapi

get /archivist/v1/tenancies:openapi

Get OpenAPI spec for Tenancies

get /archivist/v1/tenancies:openapi-ui

get /archivist/v1/tenancies:openapi-ui

Get OpenAPI UI for Tenancies

get /archivist/v1/users/tenants

get /archivist/v1/users/tenants

List User Tenants

Example Response

Tenancies API Examples

Retrieve the Current List of Root Principals

Update the List of Root Principals

Tenancies OpenAPI Docs