Setting up the AWS SDK for Kotlin - AWS SDK for Kotlin

This is prerelease documentation for a service in preview release. It is subject to change.

Setting up the AWS SDK for Kotlin

The AWS SDK for Kotlin provides Kotlin APIs for each AWS service. Using the SDK, you can build Kotlin applications that work with Amazon S3, Amazon EC2, DynamoDB, and more.

This section provides information about how to set up your development environment and projects to use the AWS SDK for Kotlin.

Overview

To make requests to AWS using the AWS SDK for Kotlin, you need the following:

  • An active AWS account

  • An AWS Identity and Access Management (IAM) user with:

    • A programmatic access key

    • Permissions to the AWS resources you’ll access using your application

  • A development environment with:

    • Your access key configured as credentials for AWS

    • Java 8 or later

    • A build automation tool

Create an account

If you do not have an AWS account, create and activate a new one.

To create a new account

Create an IAM user and programmatic access key

To use the AWS SDK for Kotlin to access AWS services, you need an AWS account and AWS credentials. To increase the security of your AWS account, we recommend that you access AWS services with an IAM user account instead of using your AWS account credentials.

Note

For an overview of IAM users and why they are important for the security of your account, see AWS security credentials in the Amazon Web Services General Reference.

For instructions on creating an access key for an existing IAM user, see Programmatic access in the IAM User Guide.

To create an IAM user and programmatic acess key

  1. Go to the IAM console (you may need to sign in to AWS first).

  2. Click Users in the sidebar to view your IAM users.

  3. If you don’t have any IAM users set up, click Create New Users to create one.

  4. Select the IAM user in the list that you’ll use to access AWS.

  5. Open the Security Credentials tab, and click Create Access Key.

    Note

    You can have a maximum of two active access keys for any given IAM user. If your IAM user has two access keys already, then you’ll need to delete one of them before creating a new key.

  6. On the resulting dialog box, click the Download Credentials button to download the credential file to your computer. Or you can click Show User Security Credentials to view the IAM user’s access key ID and secret access key, which you can copy and paste.

    Important

    There is no way to obtain the secret access key once you close the dialog box. You can, however, delete its associated access key ID and create a new one.

Set default credentials and region

To make requests to AWS using the AWS SDK for Kotlin, you must use cryptographically-signed credentials issued by AWS. With AWS SDKs and Tools like the AWS SDK for Kotlin, you use a programmatic access key, consisting of an Access Key ID and and a Secret Access Key, as credentials. You should set your credentials as the default credentials for accessing AWS with your application.

If you already have an IAM account created, see Create an IAM user and programmatic access key for instructions on creating a programmatic access key.

You should also set a default AWS Region for accessing AWS with your application. Some operations require a Region to be set. For the best network performance, you can select a Region that is geographically near to you or your customers.

To set default credentials and region

The most common way to set the default credentials and AWS Region is to use the shared config and credentials files. You can also use environment variables to set the default credentials and Region.

Setting the default credentials

Select one of these options to set the default credentials:

  • Set 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

This file should contain lines in the following format:

[default] aws_access_key_id = your_access_key_id aws_secret_access_key = your_secret_access_key

Substitute your own AWS credentials values for the values your_access_key_id and your_secret_access_key.

  • Set the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.

To set these variables on Linux, macOS, or Unix, use export :

export AWS_ACCESS_KEY_ID=your_access_key_id export AWS_SECRET_ACCESS_KEY=your_secret_access_key

To set these variables on Windows, use set :

set AWS_ACCESS_KEY_ID=your_access_key_id set AWS_SECRET_ACCESS_KEY=your_secret_access_key

Setting the default region

Select one of these options to set the default Region:

  • Set the AWS Region in the AWS config file on your local system, located at:

    • ~/.aws/config on Linux, macOS, or Unix

    • C:\Users\USERNAME\.aws\config on Windows

This file should contain lines in the following format:

[default] region = your_aws_region

Substitute your desired AWS Region (for example, "us-east-1") for your_aws_region.

  • Set the AWS_REGION environment variable.

On Linux, macOS, or Unix, use export :

export AWS_REGION=your_aws_region

On Windows, use set :

set AWS_REGION=your_aws_region

Where your_aws_region is the desired AWS Region name.

For additional information about setting credentials and Region, see The .aws/credentials and .aws/config files, AWS Region, and Using environment variables in the AWS SDKs and Tools Reference Guide.

Install Java and a build tool

Your development environment needs the following:

Next steps

Once you have your AWS account and development environment set up, create a Kotlin project using your preferred build tool. Then add dependencies for the AWS services that you access using your application.

Example gradle.build.kts file:

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile plugins { kotlin("jvm") version "1.5.30" application } group = "com.example" version = "1.0-SNAPSHOT" repositories { mavenCentral() } dependencies { implementation("aws.sdk.kotlin:s3:0.9.4-beta") implementation("aws.sdk.kotlin:dynamodb:0.9.4-beta") implementation("aws.sdk.kotlin:iam:0.9.4-beta") implementation("aws.sdk.kotlin:cloudwatch:0.9.4-beta") implementation("aws.sdk.kotlin:cognito:0.9.4-beta") implementation("aws.sdk.kotlin:sns:0.9.4-beta") implementation("aws.sdk.kotlin:pinpoint:0.9.4-beta") testImplementation(kotlin("test")) } tasks.withType<Test> { useJUnitPlatform() } tasks.withType<KotlinCompile>() { kotlinOptions.jvmTarget = "1.8" }