Help Center/ Organizations/ API Reference/ APIs/ Managing Accounts/ Inviting an Account to Join an Organization

Updated on 2025-04-10 GMT+08:00

View PDF

Inviting an Account to Join an Organization

Function

This API is used to send an invitation to another account. The invited account will join your organization as a member account. This API can be called only from the organization's management account.

URI

POST https://{endpoint}/v1/organizations/accounts/invite

Request Parameters

**Table 1** Request header parameters
Parameter	Mandatory	Type	Description
X-Security-Token	No	String	Security token (session token) of your temporary security credentials. If a temporary security credential is used, this header is required.

**Table 2** Request body parameters
Parameter	Mandatory	Type	Description
target	Yes	TargetDto object	ID of the account that you want to invite to join your organization.
notes	Yes	String	Additional information that you want to include in the email to the recipient account owner.
tags	No	Array of TagDto objects	List of tags you want to attach to the new account.

**Table 3** TargetDto
Parameter	Mandatory	Type	Description
type	Yes	String	Target type. It can be account ID or name.
entity	Yes	String	If you choose type:account, you must provide the account ID. If you choose type:name, you must specify the account name.

**Table 4** TagDto
Parameter	Mandatory	Type	Description
key	Yes	String	Identifier or name of the tag key.
value	Yes	String	String value associated with the tag key. You can set the tag value to an empty string, but cannot set it to NULL.

Response Parameters

Status code: 200

**Table 5** Response body parameters
Parameter	Type	Description
handshake	HandshakeDto object	Information to be exchanged between two accounts (sender and receiver) for establishing a secure relationship. For example, when a management account (the sender) invites another account (the receiver) to join its organization, the two accounts exchange information as a series of invitation (handshake) requests and responses, which are contained in this structure.

**Table 6** HandshakeDto
Parameter	Type	Description
id	String	Unique ID of an invitation (handshake). The originating account creates the ID when initiating the invitation (handshake).
urn	String	Uniform resource name of the invitation (handshake).
updated_at	String	Date and time when an invitation (handshake) request was accepted, canceled, declined, or expired.
created_at	String	Date and time when an invitation (handshake) request was made.
expired_at	String	The date and time the invitation (handshake) expires.
management_account_id	String	Unique ID of the organization's management account.
management_account_name	String	Name of the organization's management account.
organization_id	String	Unique ID of an organization.
notes	String	Additional information that you want to include in the email to the recipient account owner.
target	TargetDto object	ID of the account that you want to invite to join your organization.
status	String	Current state of the invitation (handshake). It can be pending, accepted, cancelled, declined, or expired.

**Table 7** TargetDto
Parameter	Type	Description
type	String	Target type. It can be account ID or name.
entity	String	If you choose type:account, you must provide the account ID. If you choose type:name, you must specify the account name.

Example Requests

Inviting an account to join an organization

POST https://{endpoint}/v1/organizations/accounts/invite

{
  "target" : {
    "type" : "account",
    "entity" : "05c734152f00d4200f2bc0179ac6c5e0"
  },
  "notes" : "test-notes",
  "tags" : [ {
    "key" : "keystring",
    "value" : "valuestring"
  } ]
}

Example Responses

Status code: 200

Successful.

{
  "handshake" : {
    "id" : "h-awjp43m7bz3b8jgy5v61jrfwakt3og8w",
    "urn" : "organizations::0a6d25d23900d45c0faac010e0fb4de0:policy:o-fhkmi6mek7wlqdp6nideqhb47qwtjdsv/service_control_policy/p-b4wpejd02o66g0pvfinvsatp4t9krfum",
    "updated_at" : "2022-08-25T08:11:53Z",
    "created_at" : "2022-08-25T08:11:20Z",
    "expired_at" : "2022-09-08T08:11:20Z",
    "management_account_id" : "0a6d25d23900d45c0faac010e0fb4de0",
    "management_account_name" : "paas_iam_573331",
    "organization_id" : "o-fhkmi6mek7wlqdp6nideqhb47qwtjdsv",
    "notes" : "test-notes",
    "target" : {
      "type" : "account",
      "entity" : "05c734152f00d4200f2bc0179ac6c5e0"
    },
    "status" : "pending"
  }
}