RKVST

Invites API

Invites API Reference

Invites API Examples

Invites can be used to invite a new user into a Tenancy to access Assets and Events.

For example, inviting a new member of the organization into their organization’s tenancy.

By default, invited users will have no permissons and need to be given access to manage specific Assets and Events using ABAC policies defined by an Administrator.

For sharing Assets and Events to other organizations and tenancies externally, check out our tutorial on OBAC policies or the IAM Policies API Reference.

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

See here for additional instructions on inviting users to your Tenancy.

Invite Creation

To create an invite you need at least the invitee’s email address. Once created, it will be considered pending and once accepted the invite itself will be deleted.

It is possible to add an optional custom message:

curl -v -X POST \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    -d '{"message": "personalised message", "email": "john.doe@example.com"}' \
    "https://app.rkvst.io/archivist/iam/v1/invites"

The response is:

{
  "identity": "invites/bbbaeab8-539d-4482-9a98-f1285e7f75cb",
  "message": "personalised message",
  "email": "john.doe@example.com",
  "expiry_time": "2022-06-17T11:30:43Z"
}

Invite Retrieval

If you know the unique identity of a pending invite, GET the resource:

curl -v -X GET \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    "https://app.rkvst.io/archivist/iam/v1/invites/bbbaeab8-539d-4482-9a98-f1285e7f75cb"

The response is:

{
  "identity": "invites/bbbaeab8-539d-4482-9a98-f1285e7f75cb",
  "message": "personalised message",
  "email": "john.doe@example.com",
  "expiry_time": "2022-06-17T11:30:43Z"
}

Retrieve All Invites

To fetch all pending invites, simply GET the /invites resource:

curl -v -X GET \
    -H "@$BEARER_TOKEN_FILE" \
    -H "Content-type: application/json" \
    "https://app.rkvst.io/archivist/iam/v1/invites"

The response is:

{
  "invites": [
    {
      "identity": "invites/bbbaeab8-539d-4482-9a98-f1285e7f75cb",
      "message": "personalised message",
      "email": "john.doe@example.com",
      "expiry_time": "2022-06-17T11:30:43Z"
    },
    {
      "identity": "invites/f4e4b1b5-8186-4feb-9072-9999f89d4619",
      "message": "another personalised message",
      "email": "jane.doe@example.com",
      "expiry_time": "2022-06-17T11:30:26Z"
    },
  ],
  "next_page_token": ""
}

Invite Deletion

To delete a pending invite, issue the following request:

curl -v -X DELETE \
    -H "@$BEARER_TOKEN_FILE" \`
    -H "Content-type: application/json" \
    "https://app.rkvst.io/archivist/iam/v1/invites/bbbaeab8-539d-4482-9a98-f1285e7f75cb"

The response will be empty.

Invites OpenAPI Docs

API to manage Email Invites.

get  /archivist/v1/invites

List invites

Description: Returns a paginated list of invites

{
  "invites": [
    {
      "email": "bob@job",
      "expiry_time": "2022-05-06T07:35:21Z",
      "identity": "invites/08838336-c357-460d-902a-3aba9528dd22",
      "message": "Some text"
    }
  ],
  "page_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InN0dW50aWR"
}
Response ParameterTypeDescription
invitesarrayDescribes Invite.
next_page_tokenstringToken to retrieve the next page of results or empty if there are none.
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 invite.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.

post  /archivist/v1/invites

Create an invite

Description: This request creates a new invite. The message is the text that will be inserted into email.

{
  "email": "bob@job",
  "message": "Some text"
}
ParameterTypeDescription
emailstringEmail address of the invitee.
messagestringText to be inserted into email.

{
  "email": "bob@job",
  "expiry_time": "2022-05-06T07:35:21Z",
  "identity": "invites/08838336-c357-460d-902a-3aba9528dd22",
  "message": "Text to be inserted in email"
}
Response ParameterTypeDescription
emailstringEmail address of the invitee.
expiry_timestringinvite expiry time
identitystringUnique identification for the invite, Relative Resource Name
messagestringText to be inserted into email invite.
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 invite.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.

delete  /archivist/v1/invites/{uuid}

Delete an invite

Description: Delete the identified invite

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 invite.
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.

get  /archivist/v1/invites/{uuid}

Get an invite

Description: Returns the identified invite

{
  "email": "bob@job",
  "expiry_time": "2022-05-06T07:35:21Z",
  "identity": "invites/08838336-c357-460d-902a-3aba9528dd22",
  "message": "Text to be inserted in email"
}
Response ParameterTypeDescription
emailstringEmail address of the invitee.
expiry_timestringinvite expiry time
identitystringUnique identification for the invite, Relative Resource Name
messagestringText to be inserted into email invite.
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 invite.
404Returned when the identified invite does not exist.
429Returned when a user exceeds their subscription’s rate limit for requests.
500Returned when the underlying storage system returns an error.

get  /archivist/v1/invites:openapi

Get OpenAPI spec for Invites

Description: Get OpenAPI v2.0 spec for Invites

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.

Edit this page on GitHub

← IAM Subjects API
Locations API →