Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

CreateStreamSessionAdminShell

Creates an administrative terminal session with full access to the live runtime environment of the Amazon GameLift Streams stream session. Use the returned credentials (SessionId, StreamUrl and TokenValue) with the AWS Systems Manager Session Manager plugin for the AWS CLI to access the terminal session.

The stream session must be in one of the following statuses: ACTIVE, CONNECTED, PENDING_CLIENT_RECONNECTION, or RECONNECTING.

The StreamUrl is valid for 60 seconds. After it expires, call this operation again to get a new URL.

Important

The returned credentials grant full access to the live runtime environment of the Amazon GameLift Streams stream session. The operator who connects to the terminal session has the same level of access that your Amazon GameLift Streams applications have, including potentially user input, screen images, and application data files. Grant permissions to call this operation only to trusted IAM identities that require live runtime environment access.

Request Syntax


POST /streamgroups/Identifier/streamsessions/StreamSessionIdentifier/access HTTP/1.1

URI Request Parameters

The request uses the following URI parameters.

Identifier

The stream group that runs this stream session.

This value is an Amazon Resource Name (ARN) or ID that uniquely identifies the stream group resource. Example ARN: arn:aws:gameliftstreams:us-west-2:111122223333:streamgroup/sg-1AB2C3De4. Example ID: sg-1AB2C3De4.

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

Pattern: (^[a-zA-Z0-9-]+$)|(^arn:aws:gameliftstreams:([^: ]*):([0-9]{12}):([^: ]*)$)

Required: Yes

StreamSessionIdentifier

An Amazon Resource Name (ARN) or ID that uniquely identifies the stream session resource. Example ARN: arn:aws:gameliftstreams:us-west-2:111122223333:streamsession/sg-1AB2C3De4/ABC123def4567. Example ID: ABC123def4567.

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

Pattern: (^[a-zA-Z0-9-]+$)|(^arn:aws:gameliftstreams:([^: ]*):([0-9]{12}):([^: ]*)$)

Required: Yes

Request Body

The request does not have a request body.

Response Syntax


HTTP/1.1 200
Content-type: application/json

{
   "SessionId": "string",
   "StreamUrl": "string",
   "TokenValue": "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.

SessionId

An AWS Systems Manager session identifier that uniquely identifies the requested terminal session. Use this value with the AWS Systems Manager Session Manager plugin.

Type: String

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

StreamUrl

An AWS Systems Manager WebSocket connection endpoint for the requested terminal session.

Type: String

TokenValue

An AWS Systems Manager authentication token that authenticates your access to the session ID and WebSocket URL. This token must be treated with the same level of security as other user credentials. The token value is only valid for establishing a new connection within 60 seconds of generation.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 1024.

Errors

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

AccessDeniedException

You don't have the required permissions to access this Amazon GameLift Streams resource. Correct the permissions before you try again.

Message: Description of the error.

HTTP Status Code: 403

InternalServerException

The service encountered an internal error and is unable to complete the request.

Message: Description of the error.

HTTP Status Code: 500

ResourceNotFoundException

The resource specified in the request was not found. Correct the request before you try again.

Message: Description of the error.

HTTP Status Code: 404

StreamSessionAccessNotReadyException

The terminal connection to the stream session is not yet available. Wait before retrying the request.

Message: Description of the error.

HTTP Status Code: 409

ThrottlingException

The request was denied due to request throttling. Retry the request after the suggested wait time.

Message: Description of the error.

HTTP Status Code: 429

ValidationException

One or more parameter values in the request fail to satisfy the specified constraints. Correct the invalid parameter values before retrying the request.

Message: Description of the error.

HTTP Status Code: 400