Amazon GameLift Service
API Reference (API Version 2015-10-01)


Requests remote access to a fleet instance. Remote access is useful for debugging, gathering benchmarking data, or watching activity in real time.

Access requires credentials that match the operating system of the instance. For a Windows instance, Amazon GameLift returns a user name and password as strings for use with a Windows Remote Desktop client. For a Linux instance, Amazon GameLift returns a user name and RSA private key, also as strings, for use with an SSH client. The private key must be saved in the proper format to a .pem file before using. If you're making this request using the AWS CLI, saving the secret can be handled as part of the GetInstanceAccess request. (See the example later in this topic). For more information on remote access, see Remotely Accessing an Instance.

To request access to a specific instance, specify the IDs of the instance and the fleet it belongs to. If successful, an InstanceAccess object is returned containing the instance's IP address and a set of credentials.

Request Syntax

{ "FleetId": "string", "InstanceId": "string" }

Request Parameters

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

The request accepts the following data in JSON format.


In the following list, the required parameters are described first.


Unique identifier for a fleet that contains the instance you want access to. The fleet can be in any of the following statuses: ACTIVATING, ACTIVE, or ERROR. Fleets with an ERROR status may be accessible for a short time before they are deleted.

Type: String

Pattern: ^fleet-\S+

Required: Yes


Unique identifier for an instance you want to get access to. You can access an instance in any status.

Type: String

Pattern: [a-zA-Z0-9\.-]+

Required: Yes

Response Syntax

{ "InstanceAccess": { "Credentials": { "Secret": "string", "UserName": "string" }, "FleetId": "string", "InstanceId": "string", "IpAddress": "string", "OperatingSystem": "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.


Object that contains connection information for a fleet instance, including IP address and access credentials.

Type: InstanceAccess object


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


The service encountered an unrecoverable internal failure while processing the request. Clients can retry such requests immediately or after a waiting period.

HTTP Status Code: 500


One or more parameter values in the request are invalid. Correct the invalid parameter values before retrying.

HTTP Status Code: 400


A service resource associated with the request could not be found. Clients should not retry such requests.

HTTP Status Code: 400


The client failed authentication. Clients should not retry such requests.

HTTP Status Code: 400


Get credentials for a Linux instance

This example requests a set of credentials to remotely connect to a fleet instance running Linux.

If you're calling GetInstanceAccess programmatically, as with the JSON syntax, you need to save the returned value of Secret (an RsA private key) as a .pem file in the proper format. The returned value uses a newline (\n) to indicate a line break.

If you're calling GetInstanceAccess with the AWS CLI, you can automatically store the RSA private key as a .pem file in the proper format. See the CLI syntax example, which saves the private key to a file called MyPrivateKey.pem. Once the private key is saved, update the file permissions with the following command:

$ chmod 400 MyPrivateKey.pem

HTTP requests are authenticated using an AWS Signature Version 4 signature in the Authorization header field.

Sample Request

POST / HTTP/1.1 Host:; Accept-Encoding: identity Content-Length: 105 User-Agent: aws-cli/1.11.36 Python/2.7.9 Windows/7 botocore/1.4.93 Content-Type: application/x-amz-json-1.0 Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20170406/us-west-2/gamelift/aws4_request, SignedHeaders=content-type;host;x-amz-date;x-amz-target, Signature=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY X-Amz-Date: 20170406T004805Z X-Amz-Target: GameLift.GetInstanceAccess {"FleetId": "fleet-a7abc071-5537-4f0f-b5ee-1b5c1187565f", "InstanceId": "i-01463992e435d836c" } CLI syntax: aws gamelift get-instance-access --fleet-id "fleet-a7abc071-5537-4f0f-b5ee-1b5c1187565f" --instance-id "i-01463992e435d836c" --query 'InstanceAccess.Credentials.Secret' --output text > MyPrivateKey.pem

Sample Response

HTTP/1.1 200 OK x-amzn-RequestId: b34f8665-EXAMPLE Content-Type: application/x-amz-json-1.1 Content-Length: 1986 Date: Thu, 06 Apr 2017 00:48:07 GMT {"InstanceAccess": { "Credentials": { "Secret": "-----BEGIN RSA PRIVATE KEY-----nEXAMPLEKEYKCAQEAy7WZhaDsrA1W3mRlQtvhwyORRX8gnxgDAfRt/gx42kWXsT4rXE/b5CpSgie/\nvBoU7jLxx92pNHoFnByP+Dc21eyyz6CvjTmWA0JwfWiW5/akH7iO5dSrvC7dQkW2duV5QuUdE0QW\nZ/aNxMniGQE6XAgfwlnXVBwrerrQo+ZWQeqiUwwMkuEbLeJFLhMCvYURpUMSC1oehm449ilx9X1F\nG50TCFeOzfl8dqqCP6GzbPaIjiU19xX/azOR9V+tpUOzEL+wmXnZt3/nHPQ5xvD2OJH67km6SuPW\noPzev/D8V+x4+bHthfSjR9Y7DvQFjfBVwHXigBdtZcU2/wei8D/HYwIDAQABAoIBAGZ1kaEvnrqu\n/uler7vgIn5m7lN5LKw4hJLAIW6tUT/fzvtcHK0SkbQCQXuriHmQ2MQyJX/0kn2NfjLV/ufGxbL1\nmb5qwMGUnEpJaZD6QSSs3kICLwWUYUiGfc0uiSbmJoap/GTLU0W5Mfcv36PaBUNy5p53V6G7hXb2\nbahyWyJNfjLe4M86yd2YK3V2CmK+X/BOsShnJ36+hjrXPPWmV3N9zEmCdJjA+K15DYmhm/tJWSD9\n81oGk9TopEp7CkIfatEATyyZiVqoRq6k64iuM9JkA3OzdXzMQexXVJ1TLZVEH0E7bhlY9d8O1ozR\noQs/FiZNAx2iijCWyv0lpjE73+kCgYEA9mZtyhkHkFDpwrSM1APaL8oNAbbjwEy7Z5Mqfql+lIp1\nYkriL0DbLXlvRAH+yHPRit2hHOjtUNZh4Axv+cpg09qbUI3+43eEy24B7G/Uh+GTfbjsXsOxQx/x\np9otyVwc7hsQ5TA5PZb+mvkJ5OBEKzet9XcKwONBYELGhnEPe7cCgYEA06Vgov6YHleHui9kHuws\nayav0elc5zkxjF9nfHFJRry21R1trw2Vdpn+9g481URrpzWVOEihvm+xTtmaZlSp//lkq75XDwnU\nWA8gkn6O3QE3fq2yN98BURsAKdJfJ5RL1HvGQvTe10HLYYXpJnEkHv+Unl2ajLivWUt5pbBrKbUC\ngYBjbO+OZk0sCcpZ29sbzjYjpIddErySIyRX5gV2uNQwAjLdp9PfN295yQ+BxMBXiIycWVQiw0bH\noMo7yykABY7Ozd5wQewBQ4AdSlWSX4nGDtsiFxWiI5sKuAAeOCbTosy1s8w8fxoJ5Tz1sdoxNeGs\nArq6Wv/G16zQuAE9zK9vvwKBgF+09VI/1wJBirsDGz9whVWfFPrTkJNvJZzYt69qezxlsjgFKshy\nWBhd4xHZtmCqpBPlAymEjr/TOlbxyARmXMnIOWIAnNXMGB4KGSyl1mzSVAoQ+fqR+cJ3d0dyPl1j\njjb0Ed/NY8frlNDxAVHE8BSkdsx2f6ELEyBKJSRr9snRAoGAMrTwYneXzvTskF/S5Fyu0iOegLDa\nNWUH38v/nDCgEpIXD5Hn3qAEcju1IjmbwlvtW+nY2jVhv7UGd8MjwUTNGItdb6nsYqM2asrnF3qS\nVRkAKKKYeGjkpUfVTrW0YFjXkfcrR/V+QFL5OndHAKJXjW7a4ejJLncTzmZSpYzwApc=\n-----END RSA PRIVATE KEY-----", "UserName": "gl-user-remote" }, "FleetId": "fleet-a7abc071-5537-4f0f-b5ee-1b5c1187565f", InstanceId": "i-01463992e435d836c", "IpAddress": "", "OperatingSystem": "AMAZON_LINUX" }

See Also

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