Link Search Menu Expand Document
Centrapay Docs

Invitations

An Invitation can be used to allow users to claim ownership of a resource on the Centrapay platform.

Contents

Models

Invitation

Mandatory Fields

Field Type Description
id String The Invitation’s unique identifier.
code String The Invitation code.
type String The type of invitation. Supported values are account-membership.
resourceId String The id of the related resource.
resourceType String The type of the related resource. Supported values are account.
expiresAt Timestamp When the Invitation expires.
createdAt Timestamp When the Invitation was created.
createdBy CRN The User or API Key that created the Invitation.
updatedAt Timestamp When the Invitation was updated.
updatedBy CRN The User or API Key that updated the Invitation.

Optional Fields

Field Type Description
accepted Boolean A flag indicating whether the Invitation has been accepted.
acceptedAt Timestamp When the Invitation was accepted.
acceptedBy CRN The User or API Key that accepted the Invitation.
acceptedByAccountId String The Account id of the user accepting the Invitation.
recipientAlias String The email address of the user accepting the Invitation.
params Object Params dependent on the Invitation type.
status String The status of the invitation. Possible values are created, sent, accepted and revoked

Params

Field Type Description
role String The role assigned to the recipient, for invitations of type account-membership.
accountName String The name of the account that the recipient is invited to, for invitations of type account-membership

Operations

Create an Invitation EXPERIMENTAL

POST /api/invitations 

curl -X POST https://service.centrapay.com/api/invitations \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "account-membership",
    "resourceId": "Hopo4g34sLVdjEMBs2p19F",
    "resourceType": "account",
    "recipientAlias": "user@org.com",
    "params": {
      "role": "cashier"
    }
  }'

Required Fields

Field Type Description
type String The type of invitation. Supported values are account-membership.
resourceId String The id of the related resource.
resourceType String The type of the related resource. Supported values are account.
recipientAlias String The email address of the user accepting the Invitation.
params Object Params depending on the Invitation type.
role String The role that will be assigned to the user when the Invitation is accepted.

Example response payload 

{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "code": "WIj211vFs9cNACwBb04vQw",
  "type": "account-membership",
  "resourceId": "Hopo4g34sLVdjEMBs2p19F",
  "resourceType": "account",
  "expiresAt": "2021-08-26T00:02:49.488Z",
  "createdAt": "2021-08-25T00:02:49.488Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedAt": "2021-08-25T00:02:49.488Z",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "recipientAlias": "user@org.com",
  "params": {
    "role": "cashier",
    "accountName": "Centrapay Cafe"
  },
  "status": "created"
}

Error Responses

Status Code Description
403 INVALID_ACCOUNT_TYPE The resourceId is associated with an account with a non org type.
403 RECIPIENT_ALREADY_INVITED An active invitation for this recipientAlias and resource already exists, or the recipient has already joined the resource.

Get an Invitation by code EXPERIMENTAL

GET /api/invitations/code/{code} 

curl https://service.centrapay.com/api/invitations/code/WIj211vFs9cNACwBb04vQw \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "code": "WIj211vFs9cNACwBb04vQw",
  "type": "account-membership",
  "resourceId": "5ee0c486308f590260d9a07f",
  "resourceType": "account",
  "expiresAt": "2021-08-26T00:02:49.488Z",
  "createdAt": "2021-08-25T00:02:49.488Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedAt": "2021-08-25T00:02:49.488Z",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}

List Invitations by accountId EXPERIMENTAL

GET /api/accounts/{accountId}/invitations 

curl https://service.centrapay.com/api/accounts/{accountId}/invitations \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "items": [
    {
      "id": "DKTs3U38hdhfEqwF1JKoT2",
      "code": "WIj211vFs9cNACwBb04vQw",
      "type": "account-membership",
      "resourceId": "Hopo4g34sLVdjEMBs2p19F",
      "resourceType": "account",
      "expiresAt": "2021-08-26T00:02:49.488Z",
      "createdAt": "2021-08-25T00:02:49.488Z",
      "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
      "updatedAt": "2021-08-25T00:02:49.488Z",
      "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
      "recipientAlias": "user@org.com",
      "params": {
        "role": "account-owner",
        "accountName": "Centrapay Cafe"
      },
      "status": "created"
    },
    {
      "id": "JKKDMU38hd01hfEqwF1oT2",
      "code": "WIj211vFs9cNACwBb04vQw",
      "type": "account-membership",
      "resourceId": "Hopo4g34sLVdjEMBs2p19F",
      "resourceType": "account",
      "expiresAt": "2021-08-26T00:02:49.488Z",
      "createdAt": "2021-08-25T00:02:49.488Z",
      "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
      "updatedAt": "2021-08-25T00:02:49.488Z",
      "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
      "recipientAlias": "john.doe@org.com",
      "params": {
        "role": "cashier",
        "accountName": "Centrapay Tea Warehouse"
      },
      "status": "sent"
    }
  ]
}

Accept an Invitation EXPERIMENTAL

POST /api/invitations/{invitationId}/accept 

curl -X POST https://service.centrapay.com/api/invitations/DKTs3U38hdhfEqwF1JKoT2/accept \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WIj211vFs9cNACwBb04vQw",
    "accountId": "Jaim1Cu1Q55uooxSens6yk"
  }'

Required Fields

Field Type Description
code String The Invitation code.
accountId String The Account id of the user accepting the Invitation.

Example response payload 

{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "code": "WIj211vFs9cNACwBb04vQw",
  "type": "account-membership",
  "resourceId": "5ee0c486308f590260d9a07f",
  "resourceType": "account",
  "expiresAt": "2021-08-26T00:02:49.488Z",
  "createdAt": "2021-08-25T00:02:49.488Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "accepted": true,
  "acceptedAt": "2021-08-25T10:12:22.122Z",
  "acceptedBy": "crn::user:e2837e88-d408-11eb-8eac-3e22fb52e878",
  "acceptedByAccountId": "Jaim1Cu1Q55uooxSens6yk",
  "updatedAt": "2021-08-25T10:12:22.122Z",
  "updatedBy": "crn::user:e2837e88-d408-11eb-8eac-3e22fb52e878"
}

Error Responses

Status Code Description
403 INVITATION_EXPIRED The Invitation is expired.
403 INVITATION_ALREADY_ACCEPTED The Invitation has already been accepted.
403 RECIPIENT_ALIAS_MISMATCH The alias of the user accepting an Invitation is not the same as the recipientAlias of the Invitation.
403 INVITATION_REVOKED The Invitation was revoked.

Revoke an invitation EXPERIMENTAL

POST /api/invitations/{invitationId}/revoke 

curl -X POST https://service.centrapay.com/api/invitations/DKTs3U38hdhfEqwF1JKoT2/revoke \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "code": "WIj211vFs9cNACwBb04vQw",
  "type": "account-membership",
  "resourceId": "Hopo4g34sLVdjEMBs2p19F",
  "resourceType": "account",
  "recipientAlias": "user@org.com",
  "params": {
    "role": "cashier",
    "accountName": "Centrapay Cafe"
  },
  "createdAt": "2021-08-25T00:02:49.488Z",
  "expiresAt": "2021-08-26T00:02:49.488Z",
  "createdBy": "crn::user:1234",
  "updatedAt": "2021-08-25T00:00:00.000Z",
  "updatedBy": "crn::user:1234",
  "status": "revoked"
}

Error Responses

Status Code Description
403 INVITATION_EXPIRED The Invitation is expired.
403 INVITATION_ACCEPTED The Invitation has already been accepted.