Welcome to the Amazon Security Token Service API Reference - Amazon Security Token Service
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Welcome to the Amazon Security Token Service API Reference

Amazon provides Amazon Security Token Service (Amazon STS) as a web service that enables you to request temporary, limited-privilege credentials for Amazon Identity and Access Management (IAM) users or for users you authenticate (federated users). This guide describes the Amazon STS API. For more information, see Temporary Security Credentials in the IAM User Guide.

Note

As an alternative to using the API, you can use one of the Amazon SDKs, which consist of libraries and sample code for various programming languages and platforms such as Java, Ruby, .NET, iOS, Android, and others. The SDKs provide a convenient way to create programmatic access to Amazon STS. For example, the SDKs can cryptographically sign requests, manage errors, and retry requests automatically. For information about the Amazon SDKs, see Tools to Build on Amazon.

For information about setting up signatures and authorization through the API, see Signing Amazon 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 Amazon products, see Amazon Services That Work with IAM in the IAM User Guide.

Endpoints

By default, Amazon Security Token Service (Amazon STS) is available as a global service, and all Amazon STS requests go to a single endpoint at https://sts.amazonaws.com. Global requests map to the US East (N. Virginia) Region. Amazon recommends using Regional Amazon STS endpoints instead of the global endpoint to reduce latency, build in redundancy, and increase session token validity. For more information, see Managing Amazon STS in an Amazon Region in the IAM User Guide.

Most Amazon Regions enable operations in all Amazon services by default. These Regions automatically activate for use with Amazon STS. Some Regions, such as Asia Pacific (Hong Kong), must be manually enabled. To learn more about enabling and disabling Amazon Web Services Regions, see Managing Amazon Web Services Regions in the Amazon Web Services General Reference. When you enable these Amazon Web Services Regions, they are automatically activated for use with Amazon STS. You cannot activate the Amazon STS endpoint for a disabled Region. Tokens valid in all Amazon Web Services Regions are longer than tokens valid in Regions 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 Amazon STS, you can direct Amazon STS API calls to that Region. Amazon STS recommends you provide both the Region and endpoint when you send calls to a Regional endpoint. You can provide the Region alone for manually enabled Regions, such as Asia Pacific (Hong Kong). In this case, you direct the calls to the Amazon STS Regional endpoint. However, if you provide the Region alone for Regions enabled by default, Amazon STS directs the calls to the global endpoint of https://sts.amazonaws.com.

To view the list of Amazon STS endpoints and if they are active by default, see Writing Code to Use Amazon STS Regions in the IAM User Guide.

Recording API requests

Amazon STS supports Amazon CloudTrail, a service that records Amazon calls for your Amazon account and delivers log files to an Amazon S3 bucket. By using information collected by CloudTrail, you can determine the requests successfully sent to Amazon STS, as well as who sent the request, and when it was sent.

If you activate Amazon STS endpoints in Regions other than the default global endpoint, then you must also enable CloudTrail logging in those Regions. You must do this to record any Amazon STS API calls sent in those Regions. For more information, see Turning On CloudTrail in Additional Regions in the Amazon CloudTrail User Guide.

Amazon Security Token Service (Amazon STS) is a global service with a single endpoint at https://sts.amazonaws.com. CloudTrail logs the calls to this endpoint 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 enable it and find your log files, see the Amazon CloudTrail User Guide.