AWS Organizations

(1)

AWS Organizations

API reference

(2)

AWS Organizations: API reference

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be aﬃliated with, connected to, or sponsored by Amazon.

(3)

Welcome to the AWS Organizations API Reference

AWS Organizations is a web service that enables you to consolidate your multiple AWS accounts into an organization and centrally manage your accounts and their resources.

This guide provides descriptions of the Organizations API. For more information about using this service, see the AWS Organizations User Guide.

API version

This version of the Organizations API Reference documents the Organizations API version 2016-11-28.

NoteAs an alternative to using the API directly, you can use one of the AWS SDKs, which consist of libraries and sample code for various programming languages and platforms (Java, Ruby, .NET, iOS, Android, and more). The SDKs provide a convenient way to create programmatic access to AWS Organizations. For example, the SDKs take care of cryptographically signing requests, managing errors, and retrying requests automatically. For more information about the AWS SDKs, including how to download and install them, see Tools for Amazon Web Services.

We recommend that you use the AWS SDKs to make programmatic API calls to Organizations. However, you also can use the Organizations Query API to make direct calls to the Organizations web service. To learn more about the Organizations Query API, see Making Query Requests in the AWS Organizations User Guide. Organizations supports GET and POST requests for all actions. That is, the API doesn't require you to use GET for some actions and POST for others. However, GET requests are subject to the limitation size of a URL. Therefore, for operations that require larger sizes, use a POST request.

Signing requests

When you send HTTP requests to AWS, sign the requests so that AWS can identify who sent them. You sign requests with your AWS access key, which consists of an access key ID and a secret access key. We strongly recommend that you don't create an access key for your root account. Anyone who has the access key for your root account has unrestricted access to all the resources in your account. Instead, create an access key for an IAM user account that has administrative permissions. As another option, use AWS Security Token Service (AWS STS) to generate temporary security credentials, and use those credentials to sign requests.

To sign requests, we recommend that you use Signature Version 4. If you have an existing application that uses Signature Version 2, you don't have to update it to use Signature Version 4. However, some operations now require Signature Version 4. The documentation for operations that require version 4 indicate this requirement.

When you use the AWS Command Line Interface (AWS CLI) or one of the AWS SDKs to make requests to AWS, these tools automatically sign the requests for you with the access key that you specify when you conﬁgure the tools.

In this release, each organization can have only one root.

Support and feedback for AWS Organizations

We welcome your feedback. Send your comments to [email protected] or post your feedback and questions in the AWS Organizations support forum. For more information about the AWS support forums, see Forums Help.

(13)

Endpoint to call When using the AWS CLI or the AWS SDK

For the current release of Organizations, specify the us-east-1 Region for all AWS API and AWS CLI calls made from the commercial AWS Regions outside of China. If calling from one of the AWS Regions in China, then specify cn-northwest-1. You can do this in the AWS CLI by using these parameters and commands:

• Use the following parameter with each command to specify both the endpoint and its region:

--endpoint-url https://organizations.us-east-1.amazonaws.com (from commercial AWS Regions outside of China)

or

--endpoint-url https://organizations.cn-northwest-1.amazonaws.com.cn (from AWS Regions in China)

• Use the default endpoint, but conﬁgure your default region with this command:

aws configure set default.region us-east-1 (from commercial AWS Regions outside of China)

or

aws configure set default.region cn-northwest-1 (from AWS Regions in China)

• Use the following parameter with each command to specify the endpoint:

--region us-east-1 (from commercial AWS Regions outside of China) or

--region cn-northwest-1 (from AWS Regions in China)

For the various SDKs used to call the APIs, see the documentation for the SDK of interest to learn how to direct the requests to a speciﬁc endpoint. For more information, see Regions and Endpoints in the Amazon Web Services General Reference.

How examples are presented

The JSON returned by the AWS Organizations service as response to your requests arrives as a single long string without line breaks or formatting whitespace. The examples in this guide include both line breaks and whitespace to improve readability. When example input parameters also would result in long strings that would extend beyond the screen, we insert line breaks to enhance readability. Always submit the input as a single JSON text string.

Recording API Requests

AWS Organizations supports AWS CloudTrail, a service that records AWS API calls for your AWS account and delivers log files to an Amazon S3 bucket. By using information collected by CloudTrail, you can determine which requests the Organizations service received, who made the request and when, and so on. For more about AWS Organizations and its support for CloudTrail, see Logging AWS Organizations Events with AWS CloudTrail in the AWS Organizations User Guide. To learn more about CloudTrail, including how to turn it on and find your log files, see the AWS CloudTrail User Guide.

(14)

Actions

The following actions are supported:

• AcceptHandshake (p. 5)

• AttachPolicy (p. 11)

• CancelHandshake (p. 18)

• CreateAccount (p. 23)

• CreateGovCloudAccount (p. 32)

• CreateOrganization (p. 41)

• CreateOrganizationalUnit (p. 48)

• CreatePolicy (p. 55)

• DeclineHandshake (p. 63)

• DeleteOrganization (p. 68)

• DeleteOrganizationalUnit (p. 71)

• DeletePolicy (p. 75)

• DeregisterDelegatedAdministrator (p. 79)

• DescribeAccount (p. 85)

• DescribeCreateAccountStatus (p. 89)

• DescribeEﬀectivePolicy (p. 93)

• DescribeHandshake (p. 99)

• DescribeOrganization (p. 104)

• DescribeOrganizationalUnit (p. 107)

• DescribePolicy (p. 111)

• DetachPolicy (p. 115)

• DisableAWSServiceAccess (p. 121)

• DisablePolicyType (p. 127)

• EnableAllFeatures (p. 134)

• EnableAWSServiceAccess (p. 139)

• EnablePolicyType (p. 145)

• InviteAccountToOrganization (p. 152)

• LeaveOrganization (p. 161)

• ListAccounts (p. 167)

• ListAccountsForParent (p. 172)

• ListAWSServiceAccessForOrganization (p. 177)

• ListChildren (p. 183)

• ListCreateAccountStatus (p. 188)

• ListDelegatedAdministrators (p. 193)

• ListDelegatedServicesForAccount (p. 200)

• ListHandshakesForAccount (p. 207)

• ListHandshakesForOrganization (p. 212)

• ListOrganizationalUnitsForParent (p. 218)

• ListParents (p. 223)

• ListPolicies (p. 228)

(15)

• ListPoliciesForTarget (p. 233)

• ListRoots (p. 238)

• ListTagsForResource (p. 243)

• ListTargetsForPolicy (p. 248)

• MoveAccount (p. 253)

• RegisterDelegatedAdministrator (p. 257)

• RemoveAccountFromOrganization (p. 263)

• TagResource (p. 269)

• UntagResource (p. 275)

• UpdateOrganizationalUnit (p. 281)

• UpdatePolicy (p. 285)

(16)

AcceptHandshake

Sends a response to the originator of a handshake agreeing to the action proposed by the handshake request.

This operation can be called only by the following principals when they also have the relevant IAM permissions:

• Invitation to join or Approve all features request handshakes: only a principal from the member account.

The user who calls the API for an invitation to join must have the

organizations:AcceptHandshake permission. If you enabled all features in the organization, the user must also have the iam:CreateServiceLinkedRole permission so that AWS Organizations can create the required service-linked role named AWSServiceRoleForOrganizations. For more information, see AWS Organizations and Service-Linked Roles in the AWS Organizations User Guide.

• Enable all features ﬁnal conﬁrmation handshake: only a principal from the management account.

For more information about invitations, see Inviting an AWS account to join your organization in the AWS Organizations User Guide. For more information about requests to enable all features in the organization, see Enabling all features in your organization in the AWS Organizations User Guide.

After you accept a handshake, it continues to appear in the results of relevant APIs for only 30 days.

After that, it's deleted.

Request Syntax

{

"HandshakeId": "string"

}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 327).

The request accepts the following data in JSON format.

HandshakeId (p. 5)

The unique identiﬁer (ID) of the handshake that you want to accept.

The regex pattern for handshake ID string requires "h-" followed by from 8 to 32 lowercase letters or digits.

Type: String

Length Constraints: Maximum length of 34.

Pattern: ^h-[0-9a-z]{8,32}$

Required: Yes

(17)

Response Syntax

{

"Handshake": { "Action": "string", "Arn": "string",

"ExpirationTimestamp": number, "Id": "string",

"Parties": [ {

"Id": "string", "Type": "string"

} ],

"RequestedTimestamp": number, "Resources": [

{

"Resources": [ "HandshakeResource"

],

"Type": "string", "Value": "string"

} ],

"State": "string"

} }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Handshake (p. 6)

A structure that contains details about the accepted handshake.

Type: Handshake (p. 307) object

Errors

For information about the errors that are common to all actions, see Common Errors (p. 329).

AccessDeniedException

You don't have permissions to perform the requested operation. The user or role that is making the request must have at least one IAM permissions policy attached that grants the required permissions. For more information, see Access Management in the IAM User Guide.

HTTP Status Code: 400

AccessDeniedForDependencyException

The operation that you attempted requires you to have the iam:CreateServiceLinkedRole for organizations.amazonaws.com permission so that AWS Organizations can create the required service-linked role. You don't have that permission.

(18)

Errors

AWSOrganizationsNotInUseException

Your account isn't a member of an organization. To make this request, you must use the credentials of an account that belongs to an organization.

HTTP Status Code: 400 ConcurrentModiﬁcationException

The target of the operation is currently being modiﬁed by a diﬀerent request. Try again later.

HandshakeAlreadyInStateException

The speciﬁed handshake is already in the requested state. For example, you can't accept a handshake that was already accepted.

HandshakeConstraintViolationException

The requested operation would violate the constraint identiﬁed in the reason code.

NoteSome of the reasons in the following list might not be applicable to this speciﬁc API or operation:

• ACCOUNT_NUMBER_LIMIT_EXCEEDED: You attempted to exceed the limit on the number of accounts in an organization. Note that deleted and closed accounts still count toward your limit.

Important

If you get this exception immediately after creating the organization, wait one hour and try again. If after an hour it continues to fail with this error, contact AWS Support.

• ALREADY_IN_AN_ORGANIZATION: The handshake request is invalid because the invited account is already a member of an organization.

• HANDSHAKE_RATE_LIMIT_EXCEEDED: You attempted to exceed the number of handshakes that you can send in one day.

• INVITE_DISABLED_DURING_ENABLE_ALL_FEATURES: You can't issue new invitations to join an organization while it's in the process of enabling all features. You can resume inviting accounts after you ﬁnalize the process when all accounts have agreed to the change.

• ORGANIZATION_ALREADY_HAS_ALL_FEATURES: The handshake request is invalid because the organization has already enabled all features.

• ORGANIZATION_IS_ALREADY_PENDING_ALL_FEATURES_MIGRATION: The handshake request is invalid because the organization has already started the process to enable all features.

• ORGANIZATION_FROM_DIFFERENT_SELLER_OF_RECORD: The request failed because the account is from a diﬀerent marketplace than the accounts in the organization. For example, accounts with India addresses must be associated with the AISPL marketplace. All accounts in an organization must be from the same marketplace.

• ORGANIZATION_MEMBERSHIP_CHANGE_RATE_LIMIT_EXCEEDED: You attempted to change the membership of an account too quickly after its previous change.

• PAYMENT_INSTRUMENT_REQUIRED: You can't complete the operation with an account that doesn't have a payment instrument, such as a credit card, associated with it.

HTTP Status Code: 400 HandshakeNotFoundException

We can't ﬁnd a handshake with the HandshakeId that you speciﬁed.

(19)

Errors

InvalidHandshakeTransitionException

You can't perform the operation on the handshake in its current state. For example, you can't cancel a handshake that was already accepted or accept a handshake that was already declined.

HTTP Status Code: 400 InvalidInputException

The requested operation failed because you provided invalid values for one or more of the request parameters. This exception includes a reason that contains additional information about the violated limit:

NoteSome of the reasons in the following list might not be applicable to this speciﬁc API or operation.

• DUPLICATE_TAG_KEY: Tag keys must be unique among the tags attached to the same entity.

• IMMUTABLE_POLICY: You speciﬁed a policy that is managed by AWS and can't be modiﬁed.

• INPUT_REQUIRED: You must include a value for all required parameters.

• INVALID_EMAIL_ADDRESS_TARGET: You speciﬁed an invalid email address for the invited account owner.

• INVALID_ENUM: You speciﬁed an invalid value.

• INVALID_ENUM_POLICY_TYPE: You speciﬁed an invalid policy type string.

• INVALID_FULL_NAME_TARGET: You speciﬁed a full name that contains invalid characters.

• INVALID_LIST_MEMBER: You provided a list to a parameter that contains at least one invalid value.

• INVALID_PAGINATION_TOKEN: Get the value for the NextToken parameter from the response to a previous call of the operation.

• INVALID_PARTY_TYPE_TARGET: You speciﬁed the wrong type of entity (account, organization, or email) as a party.

• INVALID_PATTERN: You provided a value that doesn't match the required pattern.

• INVALID_PATTERN_TARGET_ID: You speciﬁed a policy target ID that doesn't match the required pattern.

• INVALID_ROLE_NAME: You provided a role name that isn't valid. A role name can't begin with the reserved preﬁx AWSServiceRoleFor.

• INVALID_SYNTAX_ORGANIZATION_ARN: You speciﬁed an invalid Amazon Resource Name (ARN) for the organization.

• INVALID_SYNTAX_POLICY_ID: You speciﬁed an invalid policy ID.

• INVALID_SYSTEM_TAGS_PARAMETER: You speciﬁed a tag key that is a system tag. You can’t add, edit, or delete system tag keys because they're reserved for AWS use. System tags don’t count against your tags per resource limit.

• MAX_FILTER_LIMIT_EXCEEDED: You can specify only one ﬁlter parameter for the operation.

• MAX_LENGTH_EXCEEDED: You provided a string parameter that is longer than allowed.

• MAX_VALUE_EXCEEDED: You provided a numeric parameter that has a larger value than allowed.

• MIN_LENGTH_EXCEEDED: You provided a string parameter that is shorter than allowed.

• MIN_VALUE_EXCEEDED: You provided a numeric parameter that has a smaller value than allowed.

• MOVING_ACCOUNT_BETWEEN_DIFFERENT_ROOTS: You can move an account only between entities in the same root.

• TARGET_NOT_SUPPORTED: You can't perform the speciﬁed operation on that target entity.

• UNRECOGNIZED_SERVICE_PRINCIPAL: You speciﬁed a service principal that isn't recognized.

(20)

Examples

ServiceException

AWS Organizations can't complete your request because of an internal service error. Try again later.

HTTP Status Code: 400 TooManyRequestsException

You have sent too many requests in too short a period of time. The quota helps protect against denial-of-service attacks. Try again later.

For information about quotas that aﬀect AWS Organizations, see Quotas for AWS Organizationsin the AWS Organizations User Guide.

Examples

Example

Diego, the owner of an organization, has previously invited Juan's account to join his organization. The following example shows Juan's account accepting the handshake and thus agreeing to the invitation.

Sample Request

POST / HTTP/1.1

X-Amz-Target: AWSOrganizationsV20161128.AcceptHandshake {"HandshakeId": "h-examplehandshakeid111"}

Sample Response

HTTP/1.1 200 OK

Content-Type: application/json { "Handshake": {

"Action": "INVITE",

"Arn": "arn:aws:organizations::111111111111:handshake/o-exampleorgid/invite/h- examplehandshakeid111",

"RequestedTimestamp": 1481656459.257, "ExpirationTimestamp": 1482952459.257, "Id": "h-examplehandshakeid111", "Parties": [

{

"Id": "o-exampleorgid", "Type": "ORGANIZATION"

}, {

"Id": "[email protected]", "Type": "EMAIL"

} ],

"Resources": [ {

"Type": "MASTER_EMAIL", "Value": "[email protected]"

},

(21)

AttachPolicy

Attaches a policy to a root, an organizational unit (OU), or an individual account. How the policy aﬀects accounts depends on the type of policy. Refer to the AWS Organizations User Guide for information about each policy type:

• AISERVICES_OPT_OUT_POLICY

• BACKUP_POLICY

• SERVICE_CONTROL_POLICY

• TAG_POLICY

This operation can be called only from the organization's management account.

Request Syntax

{ "PolicyId": "string", "TargetId": "string"

}

Request Parameters

PolicyId (p. 11)

The unique identiﬁer (ID) of the policy that you want to attach to the target. You can get the ID for the policy by calling the ListPolicies (p. 228) operation.

The regex pattern for a policy ID string requires "p-" followed by from 8 to 128 lowercase or uppercase letters, digits, or the underscore character (_).

Type: String

Pattern: ^p-[0-9a-zA-Z_]{8,128}$

Required: Yes TargetId (p. 11)

The unique identiﬁer (ID) of the root, OU, or account that you want to attach the policy to. You can get the ID by calling the ListRoots (p. 238), ListOrganizationalUnitsForParent (p. 218), or ListAccounts (p. 167) operations.

The regex pattern for a target ID string requires one of the following:

• Root - A string that begins with "r-" followed by from 4 to 32 lowercase letters or digits.

• Account - A string that consists of exactly 12 digits.

• Organizational unit (OU) - A string that begins with "ou-" followed by from 4 to 32 lowercase letters or digits (the ID of the root that the OU is in). This string is followed by a second "-" dash and from 8 to 32 additional lowercase letters or digits.

(23)

Response Elements

Type: String

Pattern: ^(r-[0-9a-z]{4,32})|(\d{12})|(ou-[0-9a-z]{4,32}-[a-z0-9]{8,32})$

Required: Yes

Response Elements

If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body.

Errors

HTTP Status Code: 400 ConstraintViolationException

Performing this operation violates a minimum or maximum value limit. For example, attempting to remove the last service control policy (SCP) from an OU or root, inviting or creating too many accounts to the organization, or attaching too many policies to an account, OU, or root. This exception includes a reason that contains additional information about the violated limit:

• ACCOUNT_CANNOT_LEAVE_ORGANIZATION: You attempted to remove the management account from the organization. You can't remove the management account. Instead, after you remove all member accounts, delete the organization itself.

• ACCOUNT_CANNOT_LEAVE_WITHOUT_PHONE_VERIFICATION: You attempted to remove an account from the organization that doesn't yet have enough information to exist as a standalone account. This account requires you to ﬁrst complete phone veriﬁcation. Follow the steps at Removing a member account from your organization in the AWS Organizations User Guide.

• ACCOUNT_CREATION_RATE_LIMIT_EXCEEDED: You attempted to exceed the number of accounts that you can create in one day.

• ACCOUNT_NUMBER_LIMIT_EXCEEDED: You attempted to exceed the limit on the number of accounts in an organization. If you need more accounts, contact AWS Support to request an increase in your limit.

(24)

Errors

Or the number of invitations that you tried to send would cause you to exceed the limit of accounts in your organization. Send fewer invitations or contact AWS Support to request an increase in the number of accounts.

NoteDeleted and closed accounts still count toward your limit.

Important

If you get this exception when running a command immediately after creating the organization, wait one hour and try again. After an hour, if the command continues to fail with this error, contact AWS Support.

• CANNOT_REGISTER_MASTER_AS_DELEGATED_ADMINISTRATOR: You attempted to register the management account of the organization as a delegated administrator for an AWS service integrated with Organizations. You can designate only a member account as a delegated administrator.

• CANNOT_REMOVE_DELEGATED_ADMINISTRATOR_FROM_ORG: You attempted to remove an account that is registered as a delegated administrator for a service integrated with your organization. To complete this operation, you must ﬁrst deregister this account as a delegated administrator.

• CREATE_ORGANIZATION_IN_BILLING_MODE_UNSUPPORTED_REGION: To create an organization in the speciﬁed region, you must enable all features mode.

• DELEGATED_ADMINISTRATOR_EXISTS_FOR_THIS_SERVICE: You attempted to register an AWS account as a delegated administrator for an AWS service that already has a delegated administrator. To complete this operation, you must ﬁrst deregister any existing delegated administrators for this service.

• EMAIL_VERIFICATION_CODE_EXPIRED: The email veriﬁcation code is only valid for a limited period of time. You must resubmit the request and generate a new verﬁcation code.

• HANDSHAKE_RATE_LIMIT_EXCEEDED: You attempted to exceed the number of handshakes that you can send in one day.

• MASTER_ACCOUNT_ADDRESS_DOES_NOT_MATCH_MARKETPLACE: To create an account in this organization, you ﬁrst must migrate the organization's management account to the marketplace that corresponds to the management account's address. For example, accounts with India

addresses must be associated with the AISPL marketplace. All accounts in an organization must be associated with the same marketplace.

• MASTER_ACCOUNT_MISSING_BUSINESS_LICENSE: Applies only to the AWS /> Regions in China.

To create an organization, the master must have a valid business license. For more information, contact customer support.

• MASTER_ACCOUNT_MISSING_CONTACT_INFO: To complete this operation, you must ﬁrst provide a valid contact address and phone number for the management account. Then try the operation again.

• MASTER_ACCOUNT_NOT_GOVCLOUD_ENABLED: To complete this operation, the management account must have an associated account in the AWS GovCloud (US-West) Region. For more information, see AWS Organizations in the AWS GovCloud User Guide.

• MASTER_ACCOUNT_PAYMENT_INSTRUMENT_REQUIRED: To create an organization with this management account, you ﬁrst must associate a valid payment instrument, such as a credit card, with the account. Follow the steps at To leave an organization when all required account information has not yet been provided in the AWS Organizations User Guide.

• MAX_DELEGATED_ADMINISTRATORS_FOR_SERVICE_LIMIT_EXCEEDED: You attempted to register more delegated administrators than allowed for the service principal.

• MAX_POLICY_TYPE_ATTACHMENT_LIMIT_EXCEEDED: You attempted to exceed the number of policies of a certain type that can be attached to an entity at one time.

• MAX_TAG_LIMIT_EXCEEDED: You have exceeded the number of tags allowed on this resource.

(25)

Errors

• MEMBER_ACCOUNT_PAYMENT_INSTRUMENT_REQUIRED: To complete this operation with this member account, you ﬁrst must associate a valid payment instrument, such as a credit card, with the account. Follow the steps at To leave an organization when all required account information has not yet been provided in the AWS Organizations User Guide.

• MIN_POLICY_TYPE_ATTACHMENT_LIMIT_EXCEEDED: You attempted to detach a policy from an entity that would cause the entity to have fewer than the minimum number of policies of a certain type required.

• ORGANIZATION_NOT_IN_ALL_FEATURES_MODE: You attempted to perform an operation that requires the organization to be conﬁgured to support all features. An organization that supports only consolidated billing features can't perform this operation.

• OU_DEPTH_LIMIT_EXCEEDED: You attempted to create an OU tree that is too many levels deep.

• OU_NUMBER_LIMIT_EXCEEDED: You attempted to exceed the number of OUs that you can have in an organization.

• POLICY_CONTENT_LIMIT_EXCEEDED: You attempted to create a policy that is larger than the maximum size.

• POLICY_NUMBER_LIMIT_EXCEEDED: You attempted to exceed the number of policies that you can have in an organization.

• SERVICE_ACCESS_NOT_ENABLED: You attempted to register a delegated administrator before you enabled service access. Call the EnableAWSServiceAccess API ﬁrst.

• TAG_POLICY_VIOLATION: You attempted to create or update a resource with tags that are not compliant with the tag policy requirements for this account.

• WAIT_PERIOD_ACTIVE: After you create an AWS account, there is a waiting period before you can remove it from the organization. If you get an error that indicates that a wait period is required, try again in a few days.

DuplicatePolicyAttachmentException

The selected policy is already attached to the speciﬁed target.

(26)

Errors

PolicyChangesInProgressException

Changes to the eﬀective policy are in progress, and its contents can't be returned. Try the operation again later.

HTTP Status Code: 400 PolicyNotFoundException

We can't ﬁnd a policy with the PolicyId that you speciﬁed.

HTTP Status Code: 400 PolicyTypeNotEnabledException

The speciﬁed policy type isn't currently enabled in this root. You can't attach policies of the speciﬁed type to entities in a root until you enable that type in the root. For more information, see Enabling All Features in Your Organization in the AWS Organizations User Guide.

HTTP Status Code: 400 ServiceException

HTTP Status Code: 400 TargetNotFoundException

We can't ﬁnd a root, OU, account, or policy with the TargetId that you speciﬁed.

HTTP Status Code: 400 TooManyRequestsException

(27)

Examples

UnsupportedAPIEndpointException

This action isn't available in the current AWS Region.

Examples

Example 1

The following example shows how to attach a policy to an OU.

Sample Request

POST / HTTP/1.1

X-Amz-Target: AWSOrganizationsV20161128.AttachPolicy

{ "TargetId": "ou-examplerootid111-exampleouid111", "PolicyId": "p-examplepolicyid111" }

Sample Response

HTTP/1.1 200 OK

Content-Type: application/json

Example 2

The following example shows how to attach a policy directly to an account.

Sample Request

POST / HTTP/1.1

X-Amz-Target: AWSOrganizationsV20161128.AttachPolicy

{ "TargetId": "333333333333", "PolicyId": "p-examplepolicyid111" }

Sample Response

HTTP/1.1 200 OK

Content-Type: application/json

CancelHandshake

Cancels a handshake. Canceling a handshake sets the handshake state to CANCELED.

This operation can be called only from the account that originated the handshake. The recipient of the handshake can't cancel it, but can use DeclineHandshake (p. 63) instead. After a handshake is canceled, the recipient can no longer respond to that handshake.

After you cancel a handshake, it continues to appear in the results of relevant APIs for only 30 days. After that, it's deleted.

Request Syntax

{ "HandshakeId": "string"

}

Request Parameters

HandshakeId (p. 18)

The unique identiﬁer (ID) of the handshake that you want to cancel. You can get the ID from the ListHandshakesForOrganization (p. 212) operation.

The regex pattern for handshake ID string requires "h-" followed by from 8 to 32 lowercase letters or digits.

Type: String

Pattern: ^h-[0-9a-z]{8,32}$

Required: Yes

Response Syntax

{

"Handshake": { "Action": "string", "Arn": "string",

"ExpirationTimestamp": number, "Id": "string",

"Parties": [ {

"Id": "string", "Type": "string"

} ],

"RequestedTimestamp": number,

(30)

Response Elements

"Resources": [ {

"Resources": [ "HandshakeResource"

],

"Type": "string", "Value": "string"

} ],

"State": "string"

} }

Response Elements

Handshake (p. 18)

A structure that contains details about the handshake that you canceled.

Type: Handshake (p. 307) object

Errors

HandshakeAlreadyInStateException

The speciﬁed handshake is already in the requested state. For example, you can't accept a handshake that was already accepted.

HTTP Status Code: 400 HandshakeNotFoundException

We can't ﬁnd a handshake with the HandshakeId that you speciﬁed.

InvalidHandshakeTransitionException

You can't perform the operation on the handshake in its current state. For example, you can't cancel a handshake that was already accepted or accept a handshake that was already declined.

(31)

Errors

HTTP Status Code: 400 ServiceException

(32)

Examples

TooManyRequestsException

Examples

Diego, the admin of an organization, previously sent an invitation to Anaya's account to join the organization. Diego later changes his mind and decides to cancel the invitation before Anaya accepts it. The following example shows Diego canceling the handshake (and the invitation it represents). The output includes a handshake object that shows that the state is now CANCELED.

Example

This example illustrates one usage of CancelHandshake.

Sample Request

POST / HTTP/1.1

X-Amz-Target: AWSOrganizationsV20161128.CancelHandshake { "HandshakeId": "h-examplehandshakeid111" }

Sample Response

HTTP/1.1 200 OK

Content-Type: application/json {

"Handshake": {

"Id": "h-examplehandshakeid111", "State":"CANCELED",

"Action": "INVITE",

"Arn": "arn:aws:organizations::111111111111:handshake/o-exampleorgid/invite/h- examplehandshakeid111",

"Parties": [ {

"Id": "o-exampleorgid", "Type": "ORGANIZATION"

}, {

"Id": "[email protected]", "Type": "EMAIL"

} ],

"Resources": [ {

"Type": "ORGANIZATION", "Value": "o-exampleorgid", "Resources": [

{

"Type": "MASTER_EMAIL", "Value": "[email protected]"

},

(33)

CreateAccount

Creates an AWS account that is automatically a member of the organization whose credentials made the request. This is an asynchronous request that AWS performs in the background. Because CreateAccount operates asynchronously, it can return a successful completion message even though account initialization might still be in progress. You might need to wait a few minutes before you can successfully access the account. To check the status of the request, do one of the following:

• Use the Id member of the CreateAccountStatus response element from this operation to provide as a parameter to the DescribeCreateAccountStatus (p. 89) operation.

• Check the CloudTrail log for the CreateAccountResult event. For information on using CloudTrail with AWS Organizations, see Logging and monitoring in AWS Organizations in the AWS Organizations User Guide.

The user who calls the API to create an account must have the organizations:CreateAccount permission. If you enabled all features in the organization, AWS Organizations creates the required service-linked role named AWSServiceRoleForOrganizations. For more information, see AWS Organizations and Service-Linked Roles in the AWS Organizations User Guide.

If the request includes tags, then the requester must have the organizations:TagResource permission.

AWS Organizations preconﬁgures the new member account with a role (named

OrganizationAccountAccessRole by default) that grants users in the management account administrator permissions in the new member account. Principals in the management account can assume the role. AWS Organizations clones the company name and address information for the new account from the organization's management account.

This operation can be called only from the organization's management account.

For more information about creating accounts, see Creating an AWS account in Your Organization in the AWS Organizations User Guide.

Important

• When you create an account in an organization using the AWS Organizations console, API, or AWS CLI commands, the information required for the account to operate as a standalone account, such as a payment method and signing the end user license agreement (EULA) is not automatically collected. If you must remove an account from your organization later, you can do so only after you provide the missing information. Follow the steps at To leave an organization as a member account in the AWS Organizations User Guide.

• If you get an exception that indicates that you exceeded your account limits for the organization, contact AWS Support.

• If you get an exception that indicates that the operation failed because your organization is still initializing, wait one hour and then try again. If the error persists, contact AWS Support.

• Using CreateAccount to create multiple temporary accounts isn't recommended. You can only close an account from the Billing and Cost Management console, and you must be signed in as the root user. For information on the requirements and process for closing an account, see Closing an AWS account in the AWS Organizations User Guide.

NoteWhen you create a member account with this operation, you can choose whether to create the account with the IAM User and Role Access to Billing Information switch enabled. If you enable it, IAM users and roles that have appropriate permissions can view billing information for the account. If you disable it, only the account root user can access billing information. For

(35)

Request Syntax

information about how to disable this switch for an account, see Granting Access to Your Billing Information and Tools.

Request Syntax

{

"AccountName": "string", "Email": "string",

"IamUserAccessToBilling": "string", "RoleName": "string",

"Tags": [ {

"Key": "string", "Value": "string"

} ] }

Request Parameters

AccountName (p. 24)

The friendly name of the member account.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 50.

Pattern: [\u0020-\u007E]+

Required: Yes Email (p. 24)

The email address of the owner to assign to the new member account. This email address must not already be associated with another AWS account. You must use a valid email address to complete account creation.

The rules for a valid email address:

• The address must be a minimum of 6 and a maximum of 64 characters long.

• All characters must be 7-bit ASCII characters.

• There must be one and only one @ symbol, which separates the local name from the domain name.

• The local name can't contain any of the following characters:

whitespace, " ' ( ) < > [ ] : ; , \ | % &

• The local name can't begin with a dot (.)

• The domain name can consist of only the characters [a-z],[A-Z],[0-9], hyphen (-), or dot (.)

• The domain name can't begin or end with a hyphen (-) or dot (.)

• The domain name must contain at least one dot

You can't access the root user of the account or remove an account that was created with an invalid email address.

(36)

Request Parameters

Type: String

Length Constraints: Minimum length of 6. Maximum length of 64.

Pattern: See rules in parameter description Required: Yes

IamUserAccessToBilling (p. 24)

If set to ALLOW, the new account enables IAM users to access account billing information if they have the required permissions. If set to DENY, only the root user of the new account can access account billing information. For more information, see Activating Access to the Billing and Cost Management Console in the AWS Billing and Cost Management User Guide.

If you don't specify this parameter, the value defaults to ALLOW, and IAM users and roles with the required permissions can access billing information for the new account.

Type: String

Valid Values: ALLOW | DENY Required: No

RoleName (p. 24) (Optional)

The name of an IAM role that AWS Organizations automatically preconﬁgures in the new member account. This role trusts the management account, allowing users in the management account to assume the role, as permitted by the management account administrator. The role has administrator permissions in the new member account.

If you don't specify this parameter, the role name defaults to OrganizationAccountAccessRole.

For more information about how to use this role to access the member account, see the following links:

• Accessing and Administering the Member Accounts in Your Organization in the AWS Organizations User Guide

• Steps 2 and 3 in Tutorial: Delegate Access Across AWS accounts Using IAM Roles in the IAM User Guide

The regex pattern that is used to validate this parameter. The pattern can include uppercase letters, lowercase letters, digits with no spaces, and any of the following characters: =,.@-

Type: String

Pattern: [\w+=,.@-]{1,64}

Required: No Tags (p. 24)

A list of tags that you want to attach to the newly created account. For each tag in the list, you must specify both a tag key and a value. You can set the value to an empty string, but you can't set it to null. For more information about tagging, see Tagging AWS Organizations resources in the AWS Organizations User Guide.

NoteIf any one of the tags is invalid or if you exceed the maximum allowed number of tags for an account, then the entire request fails and the account is not created.

(37)

Response Syntax

Type: Array of Tag (p. 326) objects Required: No

Response Syntax

{ "CreateAccountStatus": { "AccountId": "string", "AccountName": "string", "CompletedTimestamp": number, "FailureReason": "string", "GovCloudAccountId": "string", "Id": "string",

"RequestedTimestamp": number, "State": "string"

}}

Response Elements

CreateAccountStatus (p. 26)

A structure that contains details about the request to create an account. This response structure might not be fully populated when you ﬁrst receive it because account creation is an asynchronous process. You can pass the returned CreateAccountStatus ID as a parameter to DescribeCreateAccountStatus (p. 89) to get status about the progress of the request at later times. You can also check the CloudTrail log for the CreateAccountResult event. For more information, see Monitoring the Activity in Your Organization in the AWS Organizations User Guide.

Type: CreateAccountStatus (p. 299) object

AWS Organizations

AWS Organizations

API reference

AWS Organizations: API reference

Table of Contents

Welcome to the AWS Organizations API Reference

Actions

AcceptHandshake

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

AttachPolicy

Request Syntax

Request Parameters

Response Elements

Errors

Examples

Example 1

Sample Request

Sample Response

Example 2

Sample Request

Sample Response

See Also

CancelHandshake

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors

Examples

Example

Sample Request

Sample Response

See Also

CreateAccount

Request Syntax

Request Parameters

Response Syntax

Response Elements

Errors