Welcome to the AWS Security Token Service API Reference
AWS Security Token Service (AWS STS) is a web service that enables you to request temporary, limited-privilege credentials for AWS Identity and Access Management (IAM) users or for users that you authenticate (federated users). This guide describes the AWS STS API. For more information, see Temporary Security Credentials in the IAM User Guide.
As an alternative to using the API, 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, etc.). The SDKs provide a convenient way to create programmatic
access
to AWS STS. For example, the SDKs take care of cryptographically signing requests,
managing
errors, and retrying requests automatically. For information about the AWS SDKs, see
Tools to Build on AWS
For information about setting up signatures and authorization through the API, see Signing AWS API Requests in the Amazon Web Services General Reference. For general information about the Query API, see Making Query Requests in the IAM User Guide. For information about using security tokens with other AWS products, see AWS Services That Work with IAM in the IAM User Guide.
Endpoints
By default, AWS Security Token Service (AWS STS) is available as a global service,
and all AWS STS requests
go to a single endpoint at https://sts.amazonaws.com. Global requests map to
the US East (N. Virginia) Region. AWS recommends using Regional AWS STS endpoints
instead of
the global endpoint to reduce latency, build in redundancy, and increase session token
validity. For more information, see Managing AWS STS in an
AWS Region in the IAM User Guide.
Most AWS Regions are enabled for operations in all AWS services by default. Those Regions are automatically activated for use with AWS STS. Some Regions, such as Asia Pacific (Hong Kong), must be manually enabled. To learn more about enabling and disabling AWS Regions, see Managing AWS Regions in the Amazon Web Services General Reference. When you enable these AWS Regions, they are automatically activated for use with AWS STS. You cannot activate the AWS STS endpoint for a Region that is disabled. Tokens that are valid in all AWS Regions are longer than tokens that are valid in Regions that are enabled by default. Changing this setting might affect existing systems where you temporarily store tokens. For more information, see Managing Global Endpoint Session Tokens in the IAM User Guide.
After you activate a Region for use with AWS STS, you can direct AWS STS API calls
to that
Region. AWS STS recommends that you provide both the Region and endpoint when you
make calls
to a Regional endpoint. You can provide the Region alone for manually enabled Regions,
such
as Asia Pacific (Hong Kong). In this case, the calls are directed to the AWS STS Regional
endpoint.
However, if you provide the Region alone for Regions enabled by default, the calls
are
directed to the global endpoint of https://sts.amazonaws.com.
To view the list of AWS STS endpoints and whether they are active by default, see Writing Code to Use AWS STS Regions in the IAM User Guide.
Recording API requests
AWS STS supports AWS CloudTrail, which is a service that records AWS calls for your AWS account and delivers log files to an Amazon S3 bucket. By using information collected by CloudTrail, you can determine what requests were successfully made to AWS STS, who made the request, when it was made, and so on.
If you activate AWS STS endpoints in Regions other than the default global endpoint, then you must also turn on CloudTrail logging in those Regions. This is necessary to record any AWS STS API calls that are made in those Regions. For more information, see Turning On CloudTrail in Additional Regions in the AWS CloudTrail User Guide.
AWS Security Token Service (AWS STS) is a global service with a single endpoint at
https://sts.amazonaws.com. Calls to this endpoint are logged as calls to a
global service. However, because this endpoint is physically located in the
US East (N. Virginia) Region, your logs list us-east-1 as the event Region. CloudTrail
does not write these logs to the US East (Ohio) Region unless you choose to include
global service logs in that Region. CloudTrail writes calls to all Regional endpoints
to their
respective Regions. For example, calls to sts.us-east-2.amazonaws.com are published
to the
US East (Ohio) Region and calls to sts.eu-central-1.amazonaws.com are published to
the
Europe (Frankfurt) Region.
For more information about CloudTrail, including how to turn it on and find your log files, see the AWS CloudTrail User Guide.
