diff --git a/apis/s3/pom.xml b/apis/s3/pom.xml
index 07fcec7b17..e1a336cb2f 100644
--- a/apis/s3/pom.xml
+++ b/apis/s3/pom.xml
@@ -37,6 +37,7 @@
     <test.s3.build-version />
     <test.s3.identity>${test.aws.identity}</test.s3.identity>
     <test.s3.credential>${test.aws.credential}</test.s3.credential>
+    <test.s3.sessionToken>${test.aws.sessionToken}</test.s3.sessionToken>
 
     <jclouds.osgi.export>org.jclouds.s3*;version="${project.version}"</jclouds.osgi.export>
     <jclouds.osgi.import>org.jclouds*;version="${project.version}",*</jclouds.osgi.import>
@@ -131,6 +132,7 @@
                     <test.s3.build-version>${test.s3.build-version}</test.s3.build-version>
                     <test.s3.identity>${test.s3.identity}</test.s3.identity>
                     <test.s3.credential>${test.s3.credential}</test.s3.credential>
+                    <test.s3.sessionToken>${test.s3.sessionToken}</test.s3.sessionToken>
                   </systemPropertyVariables>
                 </configuration>
               </execution>
diff --git a/apis/s3/src/test/java/org/jclouds/s3/S3ClientLiveTest.java b/apis/s3/src/test/java/org/jclouds/s3/S3ClientLiveTest.java
index ede55513a2..b6b53e075c 100644
--- a/apis/s3/src/test/java/org/jclouds/s3/S3ClientLiveTest.java
+++ b/apis/s3/src/test/java/org/jclouds/s3/S3ClientLiveTest.java
@@ -37,15 +37,19 @@ import java.net.URI;
 import java.net.URL;
 import java.util.Date;
 import java.util.Map;
+import java.util.Properties;
 import java.util.Set;
 import java.util.UUID;
 import java.util.concurrent.ExecutionException;
 import java.util.concurrent.TimeoutException;
 import java.util.concurrent.TimeUnit;
 
+import org.jclouds.ContextBuilder;
+import org.jclouds.aws.domain.SessionCredentials;
 import org.jclouds.blobstore.KeyNotFoundException;
 import org.jclouds.blobstore.domain.Blob;
 import org.jclouds.blobstore.integration.internal.BaseBlobStoreIntegrationTest;
+import org.jclouds.domain.Credentials;
 import org.jclouds.http.HttpResponseException;
 import org.jclouds.io.ByteStreams2;
 import org.jclouds.io.Payload;
@@ -66,6 +70,7 @@ import org.jclouds.util.Strings2;
 import org.jclouds.utils.TestUtils;
 import org.testng.annotations.Test;
 
+import com.google.common.base.Supplier;
 import com.google.common.base.Throwables;
 import com.google.common.collect.ImmutableMap;
 import com.google.common.collect.ImmutableSet;
@@ -80,10 +85,33 @@ public class S3ClientLiveTest extends BaseBlobStoreIntegrationTest {
    public static final String DEFAULT_OWNER_ID = "abc123";
    private static final ByteSource oneHundredOneConstitutions = TestUtils.randomByteSource().slice(0, 5 * 1024 * 1024 + 1);
 
+   protected String sessionToken;
+
    public S3ClientLiveTest() {
       this.provider = "s3";
    }
    
+   @Override
+   protected Properties setupProperties() {
+      Properties overrides = super.setupProperties();
+      sessionToken = setIfTestSystemPropertyPresent(overrides, provider + ".sessionToken");
+      return overrides;
+   }
+
+   @Override
+   protected ContextBuilder newBuilder() {
+      ContextBuilder builder = super.newBuilder();
+      if (sessionToken != null) {
+         builder.credentialsSupplier(new Supplier<Credentials>() {
+            @Override
+            public Credentials get() {
+               return SessionCredentials.builder().identity(identity).credential(credential).sessionToken(sessionToken).build();
+            }
+         });
+      }
+      return builder;
+   }
+
    public S3Client getApi() {
       return view.unwrapApi(S3Client.class);
    }
diff --git a/providers/aws-s3/README.md b/providers/aws-s3/README.md
new file mode 100644
index 0000000000..84e9968acd
--- /dev/null
+++ b/providers/aws-s3/README.md
@@ -0,0 +1,21 @@
+# The jclouds provider for Amazon's S3 (http://aws.amazon.com/s3/)
+
+Expects the jclouds s3 API to be present on your application's classpath.
+
+* **TODO**: Implementation status.
+* **TODO**: Supported features.
+* **TODO**: Usage example.
+
+## Running live tests
+
+Try
+
+```sh
+mvn clean install -Plive -pl :aws-s3 -Dtest=AWSS3ClientLiveTest -Dtest.aws-s3.identity=<aws_access_key_id> -Dtest.aws-s3.credential=<aws_secret_access_key>
+```
+
+optionally adding
+
+```sh
+-Dtest.aws-s3.sessionToken=<aws_session_token>
+```
diff --git a/providers/aws-s3/README.txt b/providers/aws-s3/README.txt
deleted file mode 100644
index edcab1df90..0000000000
--- a/providers/aws-s3/README.txt
+++ /dev/null
@@ -1,8 +0,0 @@
-#
-# The jclouds provider for Amazon's S3 (http://aws.amazon.com/s3/).
-#
-# Expects the jclouds s3 API to be present on your application's classpath.
-#
-# TODO: Implementation status.
-# TODO: Supported features.
-# TODO: Usage example.
diff --git a/providers/aws-s3/pom.xml b/providers/aws-s3/pom.xml
index 8f555bcbae..e0e9f084b9 100644
--- a/providers/aws-s3/pom.xml
+++ b/providers/aws-s3/pom.xml
@@ -40,6 +40,7 @@
     <test.aws-s3.build-version />
     <test.aws-s3.identity>${test.aws.identity}</test.aws-s3.identity>
     <test.aws-s3.credential>${test.aws.credential}</test.aws-s3.credential>
+    <test.aws-s3.sessionToken>${test.aws.sessionToken}</test.aws-s3.sessionToken>
     <test.blobstore.container-count>25</test.blobstore.container-count>
 
     <jclouds.osgi.export>org.jclouds.aws.s3*;version="${project.version}"</jclouds.osgi.export>
@@ -137,6 +138,7 @@
                     <test.aws-s3.build-version>${test.aws-s3.build-version}</test.aws-s3.build-version>
                     <test.aws-s3.identity>${test.aws-s3.identity}</test.aws-s3.identity>
                     <test.aws-s3.credential>${test.aws-s3.credential}</test.aws-s3.credential>
+                    <test.aws-s3.sessionToken>${test.aws-s3.sessionToken}</test.aws-s3.sessionToken>
                     <test.initializer>${test.initializer}</test.initializer>
                     <jclouds.blobstore.httpstream.url>${jclouds.blobstore.httpstream.url}</jclouds.blobstore.httpstream.url>
                     <jclouds.blobstore.httpstream.md5>${jclouds.blobstore.httpstream.md5}</jclouds.blobstore.httpstream.md5>