Updating authentication docs

docs/authentication.md

@@ -0,0 +1,36 @@
+
+There are two main components to authentication & authorization with Fineo:
+
+ * API Key
+ * SigV4 Credentials (aka. AWS Credentials)
+
+
+# API Key
+
+When you sign up, you will be given an API Key. **Keep this safe** - it ties all requests back to your tables/data. If anyone else gets access to this key, they will be able to see you information and send as you.
+
+If you lose it, you can look it up again on the [Web App - Profile](https://app.fineo.io/#/pages/profile) page.
+
+## Credentials
+
+When you sign up for Fineo through the [web application](https://app.fineo.io/), you specified an email and password. These will be user
+ username and password, respectively, and used for signing all requests to the API. This ensures that no one else can masquerade as you. It will also be used as your username/password combination when reading data through [JDBC](/jdbc/intro).
+
+As a user, you have access to all available API endpoints.
+
+### Device Credentials
+
+By default, devices only have access to the 'stream' API ([read more about writing to the stream](/write).
+
+Device credentials are specified in key/secret style keys that are compliant with the
+[AWS IAM](https://aws.amazon.com/iam/) style credentials. They will look something like this:
+
+```
+aws_access_key: AKIBJHP57RXU4RO...
+aws_secret_access_key: 5kZVWNNhf56h4iRC04DyYN3XI5elYO...
+```
+
+and can be easily used with the Fineo SDK.
+
+Please [reach out](mailto:help@fineo.io) if you need to API scope for your devices.
+

docs/client/java.md

@@ -36,7 +36,7 @@ From there, you can choose which module you want to use:
   * io.fineo.client.models:write
 
 Each module provides a basic interface of the API which you combine with a builder to create the 
-instance you can call. For instance, to use the 'StreamWrite' API, you would do: 
+instance to call. For instance, to use the 'StreamWrite' API:
 
 ```
   FineoClientBuilder builder = new FineoClientBuilder()
@@ -46,3 +46,28 @@ instance you can call. For instance, to use the 'StreamWrite' API, you would do:
 ```
 
 All the Java APIs support a synchronous and an asynchronous version of each method.
+
+## Credentials
+
+When setting up credentials with the API, create an form of AWS Credentials. The easiest way is with the ```CredentialsHelper```:
+
+```
+ AWSCredentialsProvider provider = CredentialsHelper.getHelper(key, secret);
+```
+
+The ```CredentialsHelper``` will look at the 'shape' of the credentials and attempt to provide the best ```AWSCredentialsProvider```. The key and secret provided to the `CredentialsHelper` can either be a Device key/secret combination (obtained from the 'Devices' section of the web application) or it can be the email/password combination used to sign uo for Fineo.  
+
+However, to make it even easier to get credentials, Fineo supports any form of `AWSCredentialsProvider`, a few are:
+
+  * [StaticCredentialProvider]
+  * [EnvironmentCredentialProvider]
+  * [ProfileCredentialProvider]
+  * [DefaultCredentialProvider]
+
+[Read more about AWS Credential Providers](http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSCredentialsProvider.html)
+
+
+[StaticCredentialProvider]: http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/AWSStaticCredentialsProvider.html
+[EnvironmentCredentialProvider]: http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/EnvironmentVariableCredentialsProvider.html 
+[ProfileCredentialProvider]: http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/profile/ProfileCredentialsProvider.html
+[DefaultCredentialProvider]: http://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/auth/DefaultAWSCredentialsProviderChain.html

docs/getting-started.md

@@ -1,5 +1,3 @@
-# Getting Started
-
 Welcome to the Fineo platform! With Fineo you can easily upload data from connected devices and then view that data through traditional SQL-based tools.
 
 This guide is going to walk through connecting a simple device, creating a schema, sending data and then reading the data back. Then it will show to flexibly manage mistakes and how to evolve schema.

docs/index.md

@@ -18,31 +18,10 @@ Fineo is the easiest, smartest way to build your IoT analytics. With features li
 
 we are ready to solve all your data problems, no matter what the scale.
 
-# Authentication
-
-## API Key
-
-When you sign up, you will be given an API Key. **Keep this safe** - it ties all requests back to 
-your tables/data. If anyone else gets access to this key, they will be able to see you information.
-
-## Credentials
-
-When you sign up through the application, you specified an email and password. These will be user
- username and password, respectively, and used for signing all requests to the API. This ensures 
- that no one else can masquerade as you. 
-
-Devices are also given 'access' and 'secret' keys that are compliant with the
-[AWS IAM](https://aws.amazon.com/iam/) style credentials. They will look something like this:
-
-```
-aws_access_key: AKIBJHP57RXU4RO...
-aws_secret_access_key: 5kZVWNNhf56h4iRC04DyYN3XI5elYO...
-```
-
-These credentials are used to authenticate/authorize a specific device to when making actions - 
-reading, writing, updating schema, etc.
-
-**All these credentials should be kept in a safe place.**
+# Top Links:
 
+ * [authentication](/authentication)
+ * [jdbc](/jdbc/intro)
+ * [tools](/client/tools)
 
 [getting started]: /getting-started

docs/jdbc/intro.md

@@ -95,6 +95,7 @@ hierarchy of types. For example:
 
  ```authentication=system_OR_profile;profile_name=my-profile```
 
+Note, with JDBC you should **not** attempt to create your own instance of the `AWSCredentialsProvider` to pass to the setup. Instead, use one of the above mechanisms to provide the credentials. Generally, this just means an email/password combination, unless some devices are allowed to access the JDBC data.
 
 All requests must have **both an API Key and IAM User credentials**.