The AWS SDK for Java 1.x reached end-of-support on December 31, 2025. We recommend that you migrate to the [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html) to continue receiving new features, availability improvements, and security updates. # Getting Started This section provides information about how to install, set up, and use the AWS SDK for Java. **Topics** + [Basic setup](signup-create-iam-user.md) + [Ways to get the AWS SDK for Java](setup-install.md) + [Use build tools](setup-build-tools.md) + [Temporary credentials and Region](setup-credentials.md) # Basic setup to work with AWS services ## Overview To successfully develop applications that access AWS services using the AWS SDK for Java, the following conditions are required: + You must be able to [sign in to the AWS access portal](#setup-awsaccount) available in the AWS IAM Identity Center. + The [permissions of the IAM role](https://docs.aws.amazon.com/singlesignon/latest/userguide/permissionsetsconcept.html) configured for the SDK must allow access to the AWS services that your application requires. The permissions associated with the **PowerUserAccess** AWS managed policy are sufficient for most development needs. + A development environment with the following elements: + [Shared configuration files](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) that are set up in the following way: + The `config` file contains a default profile that specifies an AWS Region. + The `credentials` file contains temporary credentials as part of a default profile. + A suitable [installation of Java](#java-dg-java-env). + A [build automation tool](setup-build-tools.md) such as [Maven](https://maven.apache.org/download.cgi) or [Gradle](https://gradle.org/install/). + A text editor to work with code. + (Optional, but recommended) An IDE (integrated development environment) such as [IntelliJ IDEA](https://www.jetbrains.com/idea/download/#section=windows), [Eclipse](https://www.eclipse.org/ide/), or [NetBeans](https://netbeans.org/downloads/). When you use an IDE, you can also integrate AWS Toolkits to more easily work with AWS services. The [AWS Toolkit for IntelliJ](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/welcome.html) and [AWS Toolkit for Eclipse](https://docs.aws.amazon.com/toolkit-for-eclipse/v1/user-guide/welcome.html) are two toolkits that you can use for Java development. **Important** The instructions in this setup section assume that you or organization uses IAM Identity Center. If your organization uses an external identity provider that works independently of IAM Identity Center, find out how you can get temporary credentials for the SDK for Java to use. Follow [these instructions](#setup-temp-creds) to add temporary credentials to the `~/.aws/credentials` file. If your identity provider adds temporary credentials automatically to the `~/.aws/credentials` file, make sure that the profile name is `[default]` so that you do not need to provide a profile name to the SDK or AWS CLI. ## Sign-in ability to the AWS access portal The AWS access portal is the web location where you manually sign in to the IAM Identity Center. The format of the URL is `d-xxxxxxxxxx.awsapps.com/start`or `your_subdomain.awsapps.com/start`. If you are not familiar with the AWS access portal, follow the guidance for account access in [Step 1 of the IAM Identity Center authentication topic](https://docs.aws.amazon.com/sdkref/latest/guide/access-sso.html#idcGettingStarted) in the AWS SDKs and Tools Reference Guide. Do not follow the Step 2 because the AWS SDK for Java 1.x does not support automatic token refresh and automatic retrieval of temporary credentials for the SDK that Step 2 describes. ## Set up shared configuration files The shared configuration files reside on your development workstation and contain basic settings used by all AWS SDKs and the AWS Command Line Interface (CLI). The shared configuration files can contain [a number of settings](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html), but these instructions set up the basic elements that are required to work with the SDK. ### Set up the shared `config` file The following example shows content of a shared `config` file. ``` [default] region=us-east-1 output=json ``` For development purposes, use the AWS Region [nearest](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/) to where you plan to run your code. For a [listing of region codes](https://docs.aws.amazon.com/general/latest/gr/rande.html#region-names-codes) to use in the `config` file see the Amazon Web Services General Reference guide. The `json` setting for the output format is one of [several possible values](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-output-format.html). Follow the guidance [in this section](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html) to create the `config` file. ### Set up temporary credentials for the SDK After you have access to an AWS account and IAM role through the AWS access portal, configure your development environment with temporary credentials for the SDK to access. **Steps to set up a local `credentials` file with temporary credentials** 1. [Create a shared `credentials` file](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html). 1. In the `credentials` file, paste the following placeholder text until you paste in working temporary credentials. ``` [default] aws_access_key_id= aws_secret_access_key= aws_session_token= ``` 1. Save the file. The file `~/.aws/credentials` should now exist on your local development system. This file contains the [[default] profile](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-profile) that the SDK for Java uses if a specific named profile is not specified. 1. [Sign in to the AWS access portal](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosignin.html). 1. Follow these instructions under the [Manual credential refresh](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html#how-to-get-temp-credentials) heading to copy IAM role credentials from the AWS access portal. 1. For step 4 in the linked instructions, choose the IAM role name that grants access for your development needs. This role typically has a name like **PowerUserAccess** or ** Developer**. 1. For step 7, select the **Manually add a profile to your AWS credentials file** option and copy the contents. 1. Paste the copied credentials into your local `credentials` file and remove any profile name that was pasted. Your file should resemble the following: ``` [default] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE ``` 1. Save the `credentials` file The SDK for Java will access these temporary credentials when it create a service client and use them for each request. The settings for the IAM role chosen in step 5a determine [how long the temporary credentials are valid](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosessionduration.html). The maximum duration is twelve hours. After the temporary credentials expire, repeat steps 4 through 7. ## Install a Java Development Environment The AWS SDK for Java V1 requires a Java 7 JDK or newer and all Java LTS (long-term support) JDK versions are supported. If you use version 1.12.767 or earlier of the SDK, you can use Java 7, but if you use version 1.12.768 or newer of the SDK, Java 8 is required. The [Maven central repository](https://central.sonatype.com/artifact/com.amazonaws/aws-java-sdk-bom) lists the latest version of the SDK for Java. The AWS SDK for Java works with the [Oracle Java SE Development Kit](https://www.oracle.com/java/technologies/downloads/) and with distributions of Open Java Development Kit (OpenJDK) such as [Amazon Corretto](https://aws.amazon.com/corretto), [Red Hat OpenJDK](https://developers.redhat.com/products/openjdk/overview), and [Adoptium](https://adoptium.net/). # Ways to get the AWS SDK for Java ## Prerequisites To use the AWS SDK for Java, you must have: + You must be able to [sign in to the AWS access portal](signup-create-iam-user.md#setup-awsaccount) available in the AWS IAM Identity Center. + A suitable [installation of Java](signup-create-iam-user.md#java-dg-java-env). + Temporary credentials set up in your local shared `credentials` file. See the [Basic setup to work with AWS services](signup-create-iam-user.md) topic for instructions on how to get set up to use the SDK for Java. ## Use a build tool to manage dependencies for the SDK for Java (recommended) We recommend using Apache Maven or Gradle with your project to access required dependencies of the SDK for Java.[ This section](setup-build-tools.md) describes how to use those tools. ## Download and extract the SDK (not recommended) We recommend that you use a build tool to access the SDK for your project, You can, however, download a prebuilt jar of latest version of the SDK . **Note** For information about how to download and build previous versions of the SDK, see [Installing previous versions of the SDK](#install-prev-sdk). 1. Download the SDK from [https://sdk-for-java.amazonwebservices.com/latest/aws-java-sdk.zip](https://sdk-for-java.amazonwebservices.com/latest/aws-java-sdk.zip). 1. After downloading the SDK, extract the contents into a local directory. The SDK contains the following directories: + `documentation`- contains the API documentation (also available on the web: [AWS SDK for Java API Reference](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/)). + `lib`- contains the SDK `.jar` files. + `samples`- contains working sample code that demonstrates how to use the SDK. + `third-party/lib`- contains third-party libraries that are used by the SDK, such as Apache commons logging, AspectJ and the Spring framework. To use the SDK, add the full path to the `lib` and `third-party` directories to the dependencies in your build file, and add them to your java `CLASSPATH` to run your code. ## Build previous versions of the SDK from source (not recommended) Only the latest version of the complete SDK is provided in pre-built form as a downloadable jar. However, you can build a previous version of the SDK using Apache Maven (open source). Maven will download all necessary dependencies, build and install the SDK in one step. Visit [http://maven.apache.org/](http://maven.apache.org/) for installation instructions and more information. 1. Go to the SDK’s GitHub page at: [AWS SDK for Java (GitHub)](https://github.com/aws/aws-sdk-java). 1. Choose the tag corresponding to the version number of the SDK that you want. For example, `1.6.10`. 1. Click the **Download ZIP** button to download the version of the SDK you selected. 1. Unzip the file to a directory on your development system. On many systems, you can use your graphical file manager to do this, or use the `unzip` utility in a terminal window. 1. In a terminal window, navigate to the directory where you unzipped the SDK source. 1. Build and install the SDK with the following command ([Maven](https://maven.apache.org/) required): ``` mvn clean install -Dgpg.skip=true ``` The resulting `.jar` file is built into the `target` directory. 1. (Optional) Build the API Reference documentation using the following command: ``` mvn javadoc:javadoc ``` The documentation is built into the `target/site/apidocs/` directory. # Use build tools The use of build tools helps manage the development of Java projects. Several build tools are available, but we show how to get up and running with two popular build tools--Maven and Gradle. This topic shows you how to use these build tools manage the SDK for Java dependencies that you need for your projects. **Topics** + [Use the SDK with Apache Maven](setup-project-maven.md) + [Use the SDK with Gradle](setup-project-gradle.md) # Use the SDK with Apache Maven You can use [Apache Maven](https://maven.apache.org/) to configure and build AWS SDK for Java projects, or to build the SDK itself. **Note** You must have Maven installed to use the guidance in this topic. If it isn’t already installed, visit [http://maven.apache.org/](http://maven.apache.org/) to download and install it. ## Create a new Maven package To create a basic Maven package, open a terminal (command-line) window and run: ``` mvn -B archetype:generate \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DgroupId=org.example.basicapp \ -DartifactId=myapp ``` Replace *org.example.basicapp* with the full package namespace of your application, and *myapp* with the name of your project (this will become the name of the directory for your project). By default, creates a project template for you using the [quickstart](http://maven.apache.org/archetypes/maven-archetype-quickstart/) archetype, which is a good starting place for many projects. There are more archetypes available; visit the [Maven archetypes](https://maven.apache.org/archetypes/index.html) page for a list of archetypes packaged with . You can choose a particular archetype to use by adding the `-DarchetypeArtifactId` argument to the `archetype:generate` command. For example: ``` mvn archetype:generate \ -DarchetypeGroupId=org.apache.maven.archetypes \ -DarchetypeArtifactId=maven-archetype-webapp \ -DgroupId=org.example.webapp \ -DartifactId=mywebapp ``` **Note** Much more information about creating and configuring projects is provided in the [Maven Getting Started Guide](https://maven.apache.org/guides/getting-started/). ## Configure the SDK as a Maven dependency To use the AWS SDK for Java in your project, you’ll need to declare it as a dependency in your project’s `pom.xml` file. Beginning with version 1.9.0, you can import [individual components](#configuring-maven-individual-components) or the [entire SDK](#configuring-maven-entire-sdk). ### Specifying individual SDK modules To select individual SDK modules, use the AWS SDK for Java bill of materials (BOM) for Maven, which will ensure that the modules you specify use the same version of the SDK and that they’re compatible with each other. To use the BOM, add a `` section to your application’s `pom.xml` file, adding `aws-java-sdk-bom` as a dependency and specifying the version of the SDK you want to use: ``` com.amazonaws aws-java-sdk-bom 1.11.1000 pom import ``` To view the latest version of the AWS SDK for Java BOM that is available on Maven Central, visit: [https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom](https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom). You can also use this page to see which modules (dependencies) are managed by the BOM that you can include within the `` section of your project’s `pom.xml` file. You can now select individual modules from the SDK that you use in your application. Because you already declared the SDK version in the BOM, you don’t need to specify the version number for each component. ``` com.amazonaws aws-java-sdk-s3 com.amazonaws aws-java-sdk-dynamodb ``` You can also refer to the * AWS Code Sample Catalog * to learn what dependencies to use for a given AWS service. Refer to the POM file under a specific service example. For example, if you are interested in the dependencies for the AWS S3 service, see the [complete example](https://github.com/awsdocs/aws-doc-sdk-examples/blob/master/java/example_code/s3/src/main/java/aws/example/s3/GetAcl.java) on GitHub. (Look at the pom under /java/example\$1code/s3). ### Importing all SDK modules If you would like to pull in the *entire* SDK as a dependency, don’t use the BOM method, but simply declare it in your `pom.xml` like this: ``` com.amazonaws aws-java-sdk 1.11.1000 ``` ## Build your project Once you have your project set up, you can build it using Maven’s `package` command: ``` mvn package ``` This will create your `–0—jar` file in the `target` directory. ## Build the SDK with Maven You can use Apache Maven to build the SDK from source. To do so, [download the SDK code from GitHub](https://github.com/aws/aws-sdk-java), unpack it locally, and then execute the following Maven command: ``` mvn clean install ``` # Use the SDK with Gradle To manage SDK dependencies for your [Gradle](https://gradle.com/) project, import the Maven BOM for the AWS SDK for Java into the application's `build.gradle` file. **Note** In the following examples, replace *1.12.529* in the build file with a valid version of the AWS SDK for Java. Find the latest version in the [ Maven central repository](https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom/latest). ## Project setup for Gradle 4.6 or higher [Since Gradle 4.6](https://docs.gradle.org/4.6/release-notes.html#bom-import), you can use Gradle’s improved POM support feature to import bill of materials (BOM) files by declaring a dependency on a BOM. 1. If you’re using Gradle 5.0 or later, skip to step 2. Otherwise, enable the *IMPROVED\$1POM\$1SUPPORT* feature in the `settings.gradle` file. ``` enableFeaturePreview('IMPROVED_POM_SUPPORT') ``` 1. Add the BOM to the *dependencies* section of the application's `build.gradle` file. ``` ... dependencies { implementation platform('com.amazonaws:aws-java-sdk-bom:1.12.529') // Declare individual SDK dependencies without version ... } ``` 1. Specify the SDK modules to use in the *dependencies* section. For example, the following includes a dependency for Amazon Simple Storage Service (Amazon S3). ``` ... dependencies { implementation platform('com.amazonaws:aws-java-sdk-bom:1.12.529') implementation 'com.amazonaws:aws-java-sdk-s3' ... } ``` Gradle automatically resolves the correct version of your SDK dependencies by using the information from the BOM. The following is an example of a complete `build.gradle` file that includes a dependency for Amazon S3. ``` group 'aws.test' version '1.0-SNAPSHOT' apply plugin: 'java' sourceCompatibility = 1.8 repositories { mavenCentral() } dependencies { implementation platform('com.amazonaws:aws-java-sdk-bom:1.12.529') implementation 'com.amazonaws:aws-java-sdk-s3' } ``` **Note** In the previous example, replace the dependency for Amazon S3 with the dependencies of the AWS services you will use in your project. The modules (dependencies) that are managed by the AWS SDK for Java BOM are listed on [Maven central repository](https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom/latest). ## Project setup for Gradle versions earlier than 4.6 Gradle versions earlier than 4.6 lack native BOM support. To manage AWS SDK for Java dependencies for your project, use Spring’s [dependency management plugin](https://github.com/spring-gradle-plugins/dependency-management-plugin) for Gradle to import the Maven BOM for the SDK. 1. Add the dependency management plugin to your application's `build.gradle` file. ``` buildscript { repositories { mavenCentral() } dependencies { classpath "io.spring.gradle:dependency-management-plugin:1.0.9.RELEASE" } } apply plugin: "io.spring.dependency-management" ``` 1. Add the BOM to the *dependencyManagement* section of the file. ``` dependencyManagement { imports { mavenBom 'com.amazonaws:aws-java-sdk-bom:1.12.529' } } ``` 1. Specify the SDK modules that you’ll use in the *dependencies* section. For example, the following includes a dependency for Amazon S3. ``` dependencies { compile 'com.amazonaws:aws-java-sdk-s3' } ``` Gradle automatically resolves the correct version of your SDK dependencies by using the information from the BOM. The following is an example of a complete `build.gradle` file that includes a dependency for Amazon S3. ``` group 'aws.test' version '1.0' apply plugin: 'java' sourceCompatibility = 1.8 repositories { mavenCentral() } buildscript { repositories { mavenCentral() } dependencies { classpath "io.spring.gradle:dependency-management-plugin:1.0.9.RELEASE" } } apply plugin: "io.spring.dependency-management" dependencyManagement { imports { mavenBom 'com.amazonaws:aws-java-sdk-bom:1.12.529' } } dependencies { compile 'com.amazonaws:aws-java-sdk-s3' testCompile group: 'junit', name: 'junit', version: '4.11' } ``` **Note** In the previous example, replace the dependency for Amazon S3 with the dependencies of the AWS service you will use in your project. The modules (dependencies) that are managed by the AWS SDK for Java BOM are listed on [Maven central repository](https://mvnrepository.com/artifact/com.amazonaws/aws-java-sdk-bom/latest). For more information about specifying SDK dependencies by using the BOM, see [Using the SDK with Apache Maven](setup-project-maven.md). # Set up AWS temporary credentials and AWS Region for development To connect to any of the supported services with the AWS SDK for Java, you must provide AWS temporary credentials. The AWS SDKs and CLIs use *provider chains* to look for AWS temporary credentials in a number of different places, including system/user environment variables and local AWS configuration files. This topic provides basic information about setting up your AWS temporary credentials for local application development using the AWS SDK for Java. If you need to set up credentials for use within an EC2 instance or if you’re using the Eclipse IDE for development, refer to the following topics instead: + When using an EC2 instance, create an IAM role and then give your EC2 instance access to that role as shown in [Using IAM Roles to Grant Access to AWS Resources on Amazon EC2](java-dg-roles.md). + Set up AWS credentials within Eclipse using the [AWS Toolkit for Eclipse](https://aws.amazon.com/eclipse/). See [Set up AWS Credentials](https://docs.aws.amazon.com/toolkit-for-eclipse/v1/user-guide/setup-credentials.html) in the [AWS Toolkit for Eclipse User Guide](https://docs.aws.amazon.com/toolkit-for-eclipse/v1/user-guide/) for more information. ## Configure temporary credentials You can configure temporary credentials for the AWS SDK for Java in a number of ways, but here are the recommended approaches: + Set temporary credentials in the AWS credentials profile file on your local system, located at: + `~/.aws/credentials` on Linux, macOS, or Unix + `C:\Users\USERNAME\.aws\credentials` on Windows See the [Set up temporary credentials for the SDK](signup-create-iam-user.md#setup-temp-creds) in this guide for instructions on how to get your temporary credentials. + Set the `AWS_ACCESS_KEY_ID`,`AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` environment variables. To set these variables on Linux, macOS, or Unix, use : ``` export AWS_ACCESS_KEY_ID=your_access_key_id export AWS_SECRET_ACCESS_KEY=your_secret_access_key export AWS_SESSION_TOKEN=your_session_token ``` To set these variables on Windows, use: ``` set AWS_ACCESS_KEY_ID=your_access_key_id set AWS_SECRET_ACCESS_KEY=your_secret_access_key set AWS_SESSION_TOKEN=your_session_token ``` + For an EC2 instance, specify an IAM role and then give your EC2 instance access to that role. See [IAM Roles for Amazon EC2](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) in the Amazon EC2 User Guide for Linux Instances for a detailed discussion about how this works. Once you have set your AWS temporary credentials using one of these methods, they will be loaded automatically by the AWS SDK for Java by using the default credential provider chain. For further information about working with AWS credentials in your Java applications, see [Working with AWS Credentials](credentials.md). ## Refreshing IMDS credentials The AWS SDK for Java supports opt-in refreshing IMDS credentials in the background every 1 minute, regardless of the credential expiration time. This allows you to refresh credentials more frequently and reduces the chance that not reaching IMDS impacts the perceived AWS availability. ``` 1. // Refresh credentials using a background thread, automatically every minute. This will log an error if IMDS is down during 2. // a refresh, but your service calls will continue using the cached credentials until the credentials are refreshed 3. // again one minute later. 4. 5. InstanceProfileCredentialsProvider credentials = 6. InstanceProfileCredentialsProvider.createAsyncRefreshingProvider(true); 7. 8. AmazonS3Client.builder() 9. .withCredentials(credentials) 10. .build(); 11. 12. // This is new: When you are done with the credentials provider, you must close it to release the background thread. 13. credentials.close(); ``` ## Set the AWS Region You should set a default AWS Region that will be used for accessing AWS services with the AWS SDK for Java. For the best network performance, choose a region that’s geographically close to you (or to your customers). For a list of regions for each service, see [Regions and Endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html) in the Amazon Web Services General Reference. **Note** If you *don’t* select a region, then us-east-1 will be used by default. You can use similar techniques to setting credentials to set your default AWS region: + Set the AWS Region in the AWS config file on your local system, located at: + \$1/.aws/config on Linux, macOS, or Unix + C:\$1Users\$1USERNAME\$1.aws\$1config on Windows This file should contain lines in the following format: \$1 ``` [default] region = your_aws_region ``` \$1 Substitute your desired AWS Region (for example, "us-east-1") for *your\$1aws\$1region*. + Set the `AWS_REGION` environment variable. On Linux, macOS, or Unix, use ** `` **: ``` export AWS_REGION=your_aws_region ``` On Windows, use ** `` **: ``` set AWS_REGION=your_aws_region ``` Where *your\$1aws\$1region* is the desired AWS Region name.