AWS EC2 Instance Connect

API Reference
API Version 2018-04-02
 AWS EC2 Instance Connect API Reference

AWS EC2 Instance Connect: API Reference

Copyright © 2019 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

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 affiliated with, connected to, or sponsored by Amazon.

The AWS Documentation website is getting a new look!

Try it now and let us know what you think. Switch to the new look >>

You can return to the original look by selecting English in the language selector above.
 AWS EC2 Instance Connect API Reference

Table of Contents
Welcome ........................................................................................................................................... 1
Actions ............................................................................................................................................. 2
SendSSHPublicKey ...................................................................................................................... 3
Request Syntax .................................................................................................................. 3
Request Parameters ............................................................................................................ 3
Response Syntax ................................................................................................................ 4
Response Elements ............................................................................................................. 4
Errors ............................................................................................................................... 4
See Also ............................................................................................................................ 5
Data Types ........................................................................................................................................ 6
Common Parameters .......................................................................................................................... 7
Common Errors .................................................................................................................................. 9

API Version 2018-04-02

iii
 AWS EC2 Instance Connect API Reference

Welcome
Amazon EC2 Instance Connect enables system administrators to publish one-time use SSH public keys to
their EC2 instances, providing users a simple and secure way to connect to their instances.

This document was last published on October 28, 2019.

API Version 2018-04-02

1
 AWS EC2 Instance Connect API Reference

Actions
The following actions are supported:

• SendSSHPublicKey (p. 3)

API Version 2018-04-02

2
 AWS EC2 Instance Connect API Reference
SendSSHPublicKey

SendSSHPublicKey
Pushes an SSH public key to a particular OS user on a given EC2 instance for 60 seconds.

Request Syntax
{
"AvailabilityZone": "string",
"InstanceId": "string",
"InstanceOSUser": "string",
"SSHPublicKey": "string"
}

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

The request accepts the following data in JSON format.

AvailabilityZone (p. 3)

The availability zone the EC2 instance was launched in.

Type: String

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

Pattern: ^(\w+-){2,3}\d+\w+$

Required: Yes
InstanceId (p. 3)

The EC2 instance you wish to publish the SSH key to.

Type: String

Length Constraints: Minimum length of 10. Maximum length of 32.

Pattern: ^i-[a-f0-9]+$

Required: Yes
InstanceOSUser (p. 3)

The OS user on the EC2 instance whom the key may be used to authenticate as.

Type: String

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

Pattern: ^[A-Za-z_][A-Za-z0-9\@\._-]{0,30}[A-Za-z0-9\$_-]?$

Required: Yes
SSHPublicKey (p. 3)

The public key to be published to the instance. To use it after publication you must have the
matching private key.

API Version 2018-04-02

3
 AWS EC2 Instance Connect API Reference
Response Syntax

Type: String

Length Constraints: Minimum length of 256. Maximum length of 4096.

Required: Yes

Response Syntax
{
"RequestId": "string",
"Success": boolean
}

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.

RequestId (p. 4)

The request ID as logged by EC2 Connect. Please provide this when contacting AWS Support.

Type: String
Success (p. 4)

Indicates request success.

Type: Boolean

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

AuthException

Indicates that either your AWS credentials are invalid or you do not have access to the EC2 instance.

HTTP Status Code: 400

EC2InstanceNotFoundException

Indicates that the instance requested was not found in the given zone. Check that you have provided
a valid instance ID and the correct zone.

HTTP Status Code: 400

InvalidArgsException

Indicates that you provided bad input. Ensure you have a valid instance ID, the correct zone, and a
valid SSH public key.

HTTP Status Code: 400

ServiceException

Indicates that the service encountered an error. Follow the message's instructions and try again.

API Version 2018-04-02

4
 AWS EC2 Instance Connect API Reference
See Also

HTTP Status Code: 500

ThrottlingException

Indicates you have been making requests too frequently and have been throttled. Wait for a while
and try again. If higher call volume is warranted contact AWS Support.

HTTP Status Code: 400

See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET
• AWS SDK for C++
• AWS SDK for Go
• AWS SDK for Java
• AWS SDK for JavaScript
• AWS SDK for PHP V3
• AWS SDK for Python
• AWS SDK for Ruby V2

API Version 2018-04-02

5
 AWS EC2 Instance Connect API Reference

Data Types
The AWS EC2 Instance Connect API has no separate data types.

API Version 2018-04-02

6
 AWS EC2 Instance Connect API Reference

Common Parameters
The following list contains the parameters that all actions use for signing Signature Version 4 requests
with a query string. Any action-specific parameters are listed in the topic for that action. For more
information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web
Services General Reference.

Action

The action to be performed.

Type: string

Required: Yes
Version

The API version that the request is written for, expressed in the format YYYY-MM-DD.

Type: string

Required: Yes
X-Amz-Algorithm

The hash algorithm that you used to create the request signature.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Valid Values: AWS4-HMAC-SHA256

Required: Conditional
X-Amz-Credential

The credential scope value, which is a string that includes your access key, the date, the region you
are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is
expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request.

For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web
Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-Date

The date that is used to create the signature. The format must be ISO 8601 basic format
(YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value:
20120325T120000Z.

Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for
signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is

API Version 2018-04-02

7
 AWS EC2 Instance Connect API Reference

not required. When X-Amz-Date is used, it always overrides the value of the Date header. For
more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General
Reference.

Type: string

Required: Conditional
X-Amz-Security-Token

The temporary security token that was obtained through a call to AWS Security Token Service (AWS
STS). For a list of services that support temporary security credentials from AWS Security Token
Service, go to AWS Services That Work with IAM in the IAM User Guide.

Condition: If you're using temporary security credentials from the AWS Security Token Service, you
must include the security token.

Type: string

Required: Conditional
X-Amz-Signature

Specifies the hex-encoded signature that was calculated from the string to sign and the derived
signing key.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional
X-Amz-SignedHeaders

Specifies all the HTTP headers that were included as part of the canonical request. For more
information about specifying signed headers, see Task 1: Create a Canonical Request For Signature
Version 4 in the Amazon Web Services General Reference.

Condition: Specify this parameter when you include authentication information in a query string
instead of in the HTTP authorization header.

Type: string

Required: Conditional

API Version 2018-04-02

8
 AWS EC2 Instance Connect API Reference

Common Errors
This section lists the errors common to the API actions of all AWS services. For errors specific to an API
action for this service, see the topic for that API action.

AccessDeniedException

You do not have sufficient access to perform this action.

HTTP Status Code: 400

IncompleteSignature

The request signature does not conform to AWS standards.

HTTP Status Code: 400

InternalFailure

The request processing has failed because of an unknown error, exception or failure.

HTTP Status Code: 500

InvalidAction

The action or operation requested is invalid. Verify that the action is typed correctly.

HTTP Status Code: 400

InvalidClientTokenId

The X.509 certificate or AWS access key ID provided does not exist in our records.

HTTP Status Code: 403

InvalidParameterCombination

Parameters that must not be used together were used together.

HTTP Status Code: 400

InvalidParameterValue

An invalid or out-of-range value was supplied for the input parameter.

HTTP Status Code: 400

InvalidQueryParameter

The AWS query string is malformed or does not adhere to AWS standards.

HTTP Status Code: 400

MalformedQueryString

The query string contains a syntax error.

HTTP Status Code: 404

MissingAction

The request is missing an action or a required parameter.

HTTP Status Code: 400

API Version 2018-04-02

9
 AWS EC2 Instance Connect API Reference

MissingAuthenticationToken

The request must contain either a valid (registered) AWS access key ID or X.509 certificate.

HTTP Status Code: 403

MissingParameter

A required parameter for the specified action is not supplied.

HTTP Status Code: 400

OptInRequired

The AWS access key ID needs a subscription for the service.

HTTP Status Code: 403

RequestExpired

The request reached the service more than 15 minutes after the date stamp on the request or more
than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp
on the request is more than 15 minutes in the future.

HTTP Status Code: 400

ServiceUnavailable

The request has failed due to a temporary failure of the server.

HTTP Status Code: 503

ThrottlingException

The request was denied due to request throttling.

HTTP Status Code: 400

ValidationError

The input fails to satisfy the constraints specified by an AWS service.

HTTP Status Code: 400

API Version 2018-04-02

10