Settings reference - AWS SDKs and Tools
Creating service clientsPrecedence of settingsConfig file settings listCredentials file settings listEnvironment variables listJVM system properties list

Settings reference

SDKs provide language-specific APIs for AWS services. They take care of some of the heavy lifting necessary in successfully making API calls, including authentication, retry behavior, and more. To do this, the SDKs have flexible strategies to obtain credentials to use for your requests, to maintain settings to use with each service, and to obtain values to use for global settings.

You can find detailed information about configuration settings in the following sections:

Creating service clients

To programmatically access AWS services, SDKs use a client class/object for each AWS service. For example, if your application needs to access Amazon EC2, your application creates an Amazon EC2 client object to interface with that service. You then use the service client to make requests to that AWS service. In most SDKs, a service client object is immutable, so you must create a new client for each service to which you make requests and for making requests to the same service using a different configuration.

Precedence of settings

Global settings configure features, credential providers, and other functionality that are supported by most SDKs and have a broad impact across AWS services. All SDKs have a series of places (or sources) that they check in order to find a value for global settings. The following is the setting lookup precedence:

  1. Any explicit setting set in the code or on a service client itself takes precedence over anything else.

    • Some settings can be set on a per-operation basis, and can be changed as needed for each operation that you invoke. For the AWS CLI or AWS Tools for PowerShell, these take the form of per-operation parameters that you enter on the command line. For an SDK, explicit assignments can take the form of a parameter that you set when you instantiate an AWS service client or configuration object, or sometimes when you call an individual API.

  2. Java/Kotlin only: The JVM system property for the setting is checked. If it’s set, that value is used to configure the client.

  3. The environment variable is checked. If it’s set, that value is used to configure the client.

  4. The SDK checks the shared credentials file for the setting. If it's set, the client uses it.

  5. The shared config file for the setting. If the setting is present, the SDK uses it.

    • The AWS_PROFILE environment variable or the aws.profile JVM system property can be used to specify which profile that the SDK loads.

  6. Any default value provided by the SDK source code itself is used last.

Note

Some SDKs and tools might check in a different order. Also, some SDKs and tools support other methods of storing and retrieving parameters. For example, the AWS SDK for .NET supports an additional source called the SDK Store. For more information about providers that are unique to a SDK or tool, see the specific guide for the SDK or tool that you are using.

The order determines which methods take precedence and override others. For example, if you set up a profile in the shared config file, it's only found and used after the SDK or tool checks the other places first. This means that if you put a setting in the credentials file, it is used instead of one found in the config file. If you configure an environment variable with a setting and value, it would override that setting in both the credentials and config files. And finally, a setting on the individual operation (AWS CLI command-line parameter or API parameter) or in code would override all other values for that one command.

Config file settings list

The settings listed in the following table can be assigned in the shared AWS config file. They are global and affect all AWS services.

Setting name Details
api_versions General configuration settings
aws_access_key_id AWS access keys
aws_secret_access_key AWS access keys
aws_session_token AWS access keys
ca_bundle General configuration settings
credential_process Process credential provider
credential_source Assume role credential provider
defaults_mode Smart configuration defaults
disable_request_compression Request compression
duration_seconds Assume role credential provider
ec2_metadata_service_endpoint IMDS credential provider
ec2_metadata_service_endpoint_mode IMDS credential provider
ec2_metadata_v1_disabled IMDS credential provider
endpoint_discovery_enabled Endpoint discovery
endpoint_url Service-specific endpoints
external_id Assume role credential provider
ignore_configured_endpoint_urls Service-specific endpoints
max_attempts Retry behavior
metadata_service_num_attempts Amazon EC2 instance metadata
metadata_service_timeout Amazon EC2 instance metadata
mfa_serial Assume role credential provider
output General configuration settings
parameter_validation General configuration settings
region AWS Region
request_min_compression_size_bytes Request compression
retry_mode Retry behavior
role_arn Assume role credential provider
role_session_name Assume role credential provider
s3_disable_multiregion_access_points Amazon S3 Multi-Region Access Points
s3_use_arn_region Amazon S3 access points
source_profile Assume role credential provider
sso_account_id IAM Identity Center credential provider
sso_region IAM Identity Center credential provider
sso_registration_scopes IAM Identity Center credential provider
sso_role_name IAM Identity Center credential provider
sso_start_url IAM Identity Center credential provider
sts_regional_endpoints AWS STS Regionalized endpoints
use_dualstack_endpoint Dual-stack and FIPS endpoints
use_fips_endpoint Dual-stack and FIPS endpoints
web_identity_token_file Assume role credential provider

Credentials file settings list

The settings listed in the following table can be assigned in the shared AWS credentials file. They are global and affect all AWS services.

Setting name Details
aws_access_key_id AWS access keys
aws_secret_access_key AWS access keys
aws_session_token AWS access keys

Environment variables list

Environment variables supported by most SDKs are listed in the following table. They are global and affect all AWS services.

Setting name Details
AWS_ACCESS_KEY_ID AWS access keys
AWS_CA_BUNDLE General configuration settings
AWS_CONFIG_FILE Location of the shared config and credentials files
AWS_CONTAINER_AUTHORIZATION_TOKEN Container credential provider
AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE Container credential provider
AWS_CONTAINER_CREDENTIALS_FULL_URI Container credential provider
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI Container credential provider
AWS_DEFAULTS_MODE Smart configuration defaults
AWS_DISABLE_REQUEST_COMPRESSION Request compression
AWS_EC2_METADATA_DISABLED IMDS credential provider
AWS_EC2_METADATA_SERVICE_ENDPOINT IMDS credential provider
AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE IMDS credential provider
AWS_EC2_METADATA_V1_DISABLED IMDS credential provider
AWS_ENABLE_ENDPOINT_DISCOVERY Endpoint discovery
AWS_ENDPOINT_URL Service-specific endpoints
AWS_ENDPOINT_URL_<SERVICE> Service-specific endpoints
AWS_IAM_ROLE_ARN Assume role credential provider
AWS_IAM_ROLE_SESSION_NAME Assume role credential provider
AWS_IGNORE_CONFIGURED_ENDPOINT_URLS Service-specific endpoints
AWS_MAX_ATTEMPTS Retry behavior
AWS_METADATA_SERVICE_NUM_ATTEMPTS Amazon EC2 instance metadata
AWS_METADATA_SERVICE_TIMEOUT Amazon EC2 instance metadata
AWS_PROFILE Shared config and credentials files
AWS_REGION AWS Region
AWS_REQUEST_MIN_COMPRESSION_SIZE_BYTES Request compression
AWS_RETRY_MODE Retry behavior
AWS_S3_DISABLE_MULTIREGION_ACCESS_POINTS Amazon S3 Multi-Region Access Points
AWS_S3_USE_ARN_REGION Amazon S3 access points
AWS_SECRET_ACCESS_KEY AWS access keys
AWS_SESSION_TOKEN AWS access keys
AWS_SHARED_CREDENTIALS_FILE Location of the shared config and credentials files
AWS_STS_REGIONAL_ENDPOINTS AWS STS Regionalized endpoints
AWS_USE_DUALSTACK_ENDPOINT Dual-stack and FIPS endpoints
AWS_USE_FIPS_ENDPOINT Dual-stack and FIPS endpoints
AWS_WEB_IDENTITY_TOKEN_FILE Assume role credential provider

JVM system properties list

You can use the following JVM system properties for the AWS SDK for Java and the AWS SDK for Kotlin (targeting the JVM). See How to set JVM system properties for instructions on how to set JVM system properties.

Setting name Details
aws.accessKeyId AWS access keys
aws.configFile Location of the shared config and credentials files
aws.defaultsMode Smart configuration defaults
aws.disableEc2MetadataV1 IMDS credential provider
aws.disableRequestCompression Request compression
aws.ec2MetadataServiceEndpoint IMDS credential provider
aws.ec2MetadataServiceEndpointMode IMDS credential provider
aws.endpointDiscoveryEnabled Endpoint discovery
aws.endpointUrl Service-specific endpoints
aws.endpointUrl<ServiceName> Service-specific endpoints
aws.ignoreConfiguredEndpointUrls Service-specific endpoints
aws.maxAttempts Retry behavior
aws.profile Shared config and credentials files
aws.region AWS Region
aws.requestMinCompressionSizeBytes Request compression
aws.retryMode Retry behavior
aws.roleArn Assume role credential provider
aws.roleSessionName Assume role credential provider
aws.s3DisableMultiRegionAccessPoints Amazon S3 Multi-Region Access Points
aws.s3UseArnRegion Amazon S3 access points
aws.secretAccessKey AWS access keys
aws.sessionToken AWS access keys
aws.sharedCredentialsFile Location of the shared config and credentials files
aws.useDualstackEndpoint Dual-stack and FIPS endpoints
aws.useFipsEndpoint Dual-stack and FIPS endpoints
aws.webIdentityTokenFile Assume role credential provider