AWS services or capabilities described in AWS documentation might vary by Region.
To see the differences applicable to the China Regions, see Getting Started with Amazon AWS.

GetSessionToken

Returns a set of temporary credentials for an AWS account or IAM user. The
credentials consist of an access key ID, a secret access key, and a security token.
Typically,
you use GetSessionToken if you want to use MFA to protect programmatic calls to
specific AWS API operations like Amazon EC2 StopInstances. MFA-enabled IAM users
would need to call GetSessionToken and submit an MFA code that is associated with
their MFA device. Using the temporary security credentials that are returned from
the call,
IAM users can then make programmatic calls to API operations that require MFA
authentication. If you do not supply a correct MFA code, then the API returns an access
denied
error. For a comparison of GetSessionToken with the other API operations that
produce temporary credentials, see Requesting Temporary Security
Credentials and Comparing the
AWS STS API operations in the IAM User Guide.

The GetSessionToken operation must be called by using the long-term AWS
security credentials of the AWS account or an IAM user. Credentials that are created
by
IAM users are valid for the duration that you specify. This duration can range from
900
seconds (15 minutes) up to a maximum of 129,600 seconds (36 hours), with a default
of 43,200
seconds (12 hours). Credentials that are created by using account credentials can
range from
900 seconds (15 minutes) up to a maximum of 3,600 seconds (1 hour), with a default
of 1 hour.

The temporary security credentials created by GetSessionToken can be used
to make API calls to any AWS service with the following exceptions:

You cannot call any IAM API operations unless MFA authentication information is
included in the request.

You cannot call any STS API exceptAssumeRole or GetCallerIdentity.

Note

We recommend that you do not call GetSessionToken with AWS account
root user credentials. Instead, follow our best practices by
creating one or more IAM users, giving them the necessary permissions, and using IAM
users for everyday interaction with AWS.

The permissions associated with the temporary security credentials returned by
GetSessionToken are based on the permissions associated with account or IAM
user whose credentials are used to call the operation. If GetSessionToken is
called using AWS account root user credentials, the temporary credentials have root
user
permissions. Similarly, if GetSessionToken is called using the credentials of an
IAM user, the temporary credentials have the same permissions as the IAM user.

Request Parameters

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

DurationSeconds

The duration, in seconds, that the credentials should remain valid. Acceptable
durations for IAM user sessions range from 900 seconds (15 minutes) to 129,600 seconds
(36
hours), with 43,200 seconds (12 hours) as the default. Sessions for AWS account owners
are
restricted to a maximum of 3,600 seconds (one hour). If the duration is longer than
one hour,
the session for AWS account owners defaults to one hour.

Type: Integer

Valid Range: Minimum value of 900. Maximum value of 129600.

Required: No

SerialNumber

The identification number of the MFA device that is associated with the IAM user who
is making the GetSessionToken call. Specify this value if the IAM user has a
policy that requires MFA authentication. The value is either the serial number for
a hardware
device (such as GAHT12345678) or an Amazon Resource Name (ARN) for a virtual
device (such as arn:aws:iam::123456789012:mfa/user). You can find the device for
an IAM user by going to the AWS Management Console and viewing the user's security
credentials.

The regex used to validate this parameter is a string of
characters consisting of upper- and lower-case alphanumeric characters with no spaces.
You can also include underscores or any of the following characters: =,.@:/-

Type: String

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

Pattern: [\w+=/:,.@-]*

Required: No

TokenCode

The value provided by the MFA device, if MFA is required. If any policy requires the
IAM user to submit an MFA code, specify this value. If MFA authentication is required,
the
user must provide a code when requesting a set of temporary security credentials.
A user who
fails to provide the code receives an "access denied" response when requesting resources
that
require MFA authentication.

The format for this parameter, as described by its regex pattern, is a sequence of
six
numeric digits.

Type: String

Length Constraints: Fixed length of 6.

Pattern: [\d]*

Required: No

Response Elements

The following element is returned by the service.

Credentials

The temporary security credentials, which include an access key ID, a secret access
key, and a security (or session) token.

Note

The size of the security token that STS API operations return is not fixed. We
strongly recommend that you make no assumptions about the maximum size. As of this
writing,
the typical size is less than 4096 bytes, but that can vary. Also, future updates
to AWS
might require larger sizes.

Errors

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

RegionDisabled

STS is not activated in the requested region for the account that is being asked to
generate
credentials. The account administrator must use the IAM console to activate STS in
that
region. For more information, see Activating and Deactivating AWS
STS in an AWS Region in the IAM User Guide.