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

Updated on 2024-05-28 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.

Debugging

You can debug this API through automatic authentication in API Explorer or use the SDK sample code generated by API Explorer.

URI

POST /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. Minimum: 1

**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. Maximum: 1024
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 or email. Minimum: 1 Maximum: 64
entity	Yes	String	If you choose type:account, you must provide the account ID. If you choose type:email, you must specify the email address that is associated with the account. Maximum: 100

**Table 4** TagDto
Parameter	Mandatory	Type	Description
key	Yes	String	Identifier or name of the tag key. Minimum: 1 Maximum: 128
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. Minimum: 0 Maximum: 255

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). Maximum: 34
urn	String	Uniform resource name of the invitation (handshake). Minimum: 1 Maximum: 1500
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.
management_account_id	String	Unique ID of the organization's management account. Maximum: 64
management_account_name	String	Name of the organization's management account. Maximum: 64
organization_id	String	Unique ID of an organization. Maximum: 34
notes	String	Additional information that you want to include in the email to the recipient account owner. Maximum: 1024
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. Minimum: 1 Maximum: 64

**Table 7** TargetDto
Parameter	Type	Description
type	String	Target type. It can be account or email. Minimum: 1 Maximum: 64
entity	String	If you choose type:account, you must provide the account ID. If you choose type:email, you must specify the email address that is associated with the account. Maximum: 100

Example Requests

Inviting an account to join an organization

POST https://{hostname}/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",
    "management_account_id" : "0a6d25d23900d45c0faac010e0fb4de0",
    "management_account_name" : "paas_iam_573331",
    "organization_id" : "o-fhkmi6mek7wlqdp6nideqhb47qwtjdsv",
    "notes" : "test-notes",
    "target" : {
      "type" : "account",
      "entity" : "05c734152f00d4200f2bc0179ac6c5e0"
    },
    "status" : "pending"
  }
}