Added get started and OAuth startup flow (iZettle#145)

* Draft for getting started with a dev account and OAuth

Author: Astro-Choco

get-started/user-guides/sign-up-for-a-developer-account.md

@@ -0,0 +1,26 @@
+Sign up for a Zettle developer account
+===
+Before you start to build an app with Zettle, you need to sign up for a Zettle developer account.
+
+* [Prerequisites](#prerequisites)
+* [Sign up for a Zettle developer account](#sign-up-for-a-zettle-developer-account)
+* [Next task](#next-task)
+* [Related API reference](#related-api-reference)
+
+## Prerequisites
+* None
+
+## Sign up for a Zettle developer account
+
+1. Create an account at [Zettle Developer Portal](https://developer.zettle.com/register).
+2. Go to your email and find an email from Zettle that asks you to verify your email address.
+3. Follow the instruction in the email to verify your email address.
+   
+   After that, you will receive a welcome email from Zettle with the Developer Platform Agreement. Now you're ready to start building with Zettle.
+
+## Next task
+* To build a self-hosted app that is hosted by merchants individually, [create a self-hosted app](../../oauth-api/user-guides/create-an-app/create-a-self-hosted-app).
+* To build a partner-hosted app that is hosted by you as an integrator, [create a partner-hosted app](../../oauth-api/user-guides/create-an-app/create-a-partner-hosted-app.md).
+
+## Related API reference
+* None

oauth-api/images/API-keys-in-Integration-tools.png

@@ -0,0 +1,55 @@
+Create a partner-hosted app
+===
+A partner-hosted app is hosted by you as an integrator. To authorise, the app uses the authorisation code grant.
+
+In an authorisation code grant flow, you use a temporary authorisation code to exchange for an access token from the authorisation server. A temporary authorisation code is generated from the authorisation server using API credentials. API credentials include a client secret and client ID.
+
+To authorise your app using authorisation code grant, you need to get API credentials for the app by creating an app in your Dashboard on the [Developer Portal](https://developer.zettle.com/).
+> **Note:** If you want to build a self-hosted app that will be hosted by merchants, [create a self-hosted app](create-a-self-hosted-app).
+
+* [Prerequisites](#prerequisites)
+* [Get API credentials for a new app](#get-api-credentials-for-a-new-app)
+* [Request a new client secret for an existing app](#request-a-new-client-secret-for-an-existing-app)
+* [Next task](#next-task)
+* [Related API reference](#related-api-reference)
+
+## Prerequisites
+* You have an account for the [Developer Portal](https://developer.zettle.com/). If you don't have an account, [sign up for a developer account](../../../get-started/user-guides/sign-up-for-a-developer-account.md).
+
+## Get API credentials for a new app
+If you need API credentials for a new app, create a public app in your Dashboard.
+ 
+1. Log in to the [Developer Portal](https://developer.zettle.com/).    
+2. On your Dashboard, click **Create a new app**. <!-- screesshot. Click or select?-->
+   
+   <img id="create-a-new-app-from-your-dashboard" src="../../images/create-a-new-app-from-your-dashboard.png" alt="This screenshot shows the Create a new app button on the right of your Dashboard." >
+3. On the Create a new app page, click **Public API credentials** to open the form for the new app.
+4. Fill in the form for the new app.
+   
+   <img id="fill-in-the-form-for-the-new-app-partner-hosted" src="../../images/fill-in-the-form-for-the-new-app-partner-hosted.png" alt="This screenshot shows a form where you fill in the app name, app URL, and the company name. Optionally, you can add OAuth Redirect URIs that redirect merchants to your app after successful login to Zettle." >
+5. Click **Get credentials** to create your API credentials.
+6. Download your API credentials and save them somewhere safe.
+   
+   <img id="download-your-API-credentials" src="../../images/download-your-API-credentials.png" alt="This screenshot shows your API credentials and the Download credentials button." >
+   
+   > **Tip:** As the client ID doesn't change, if you lose the API credentials, you can [request a new client secret](#request-a-new-client-secret-for-an-existing-app).
+
+## Request a new client secret for an existing app
+The client ID of an existing app doesn't change. If you need a new client secret for an existing app, request it in your Dashboard.
+
+1. Log in to the [Developer Portal](https://developer.zettle.com/).    
+2. On your Dashboard, choose the app for which you need to request a new secret. The current client secret is hidden.
+   
+   <img id="choose-the-app-that-needs-a-new-client-secret" src="../../images/choose-the-app-that-needs-a-new-client-secret.png" alt="This screenshot shows where you can choose the app that needs a new client secret on your Dashboard." >
+   
+3. On the app page, click **Request new client secret** to deactivate the current secret and generate a new secret. The new client secret will be shown.
+   
+   <img id="request-a-new-client-secret" src="../../images/request-a-new-client-secret.png" alt="This screenshot shows the Request new client secret button on the right of your Dashboard." >   
+
+4. Download your API credentials and save them somewhere safe.
+
+## Next task
+* [Set up authorisation code grant](../set-up-app-authorisation/set-up-authorisation-code-grant.md)
+
+## Related API reference
+* [OAuth2 API Reference](../../../authorization.md)

oauth-api/images/available-API-keys.png

@@ -0,0 +1,57 @@
+Create a self-hosted app
+===
+A self-hosted app is hosted by one or more merchants individually. To authorise, the app uses the authorisation assertion grant.
+
+In an authorisation assertion grant flow, you use a JSON web token (JWT) assertion to request an access token from the authorisation server. The JWT assertion is used as an API key. An API key is created by a merchant (Zettle merchant account owner). It's valid until the merchant revokes it.
+<!-- add assertion grant in glossary -->
+
+To authorise your app using assertion grant, you need to ask the merchant (Zettle merchant account owner) to create an API key at my.zettle.com. You can provide the merchant a deep link that directs them to the API creation page or steps to create an API key.
+
+> **Note:** If you want to build a partner-hosted app that will be hosted by you as an integrator, [create a partner-hosted app](../create-a-partner-hosted-app.md).
+
+* [Prerequisites](#prerequisites)
+* [Step 1: Get an API key from a Zettle merchant](#step-1-get-an-api-key-from-a-zettle-merchant)
+* [Step 2 (Optional): Prepare for app tracking](#step-2-optional-prepare-for-app-tracking)  
+* [Next task](#next-task)
+* [Related API reference](#related-api-reference)
+
+## Prerequisites
+* You have an account for the [Developer Portal](https://developer.zettle.com/). If you don't have an account, [sign up for a developer account](../../../../get-started/user-guides/sign-up-for-a-developer-account.md).
+
+## Step 1: Get an API key from a Zettle merchant
+An API key must be created by the Zettle merchant that will use your app.
+ 
+1. Ask the merchant to create an API key in one of the following ways:
+   * Provide the merchant a deep link with pre-populated fields and [the instructions to create an API key with the deep link](create-an-api-key.md#create-an-api-key-with-a-deep-link-from-the-developer).
+      ```
+      https://my.zettle.com/apps/api-keys?name=<key-name>&scopes=<scopes>
+      ```
+      Where:
+      * `<key-name>` should be the name under which the API key is stored. Keep it short and descriptive. One good practice is to use the integration name as the key name, for example, `WooCommerce`.
+      * `<scopes>` should contain the list of needed OAuth scopes separated by a space, for example, `READ:PURCHASE%20READ:FINANCE`.
+      
+      Example:
+      ```
+      https://my.zettle.com/apps/api-keys?name=WooCommerce&scopes=READ:PURCHASE%20READ:FINANCE
+      ```
+   * Provide the merchant OAuth scopes and [the instructions to create an API key with the OAuth scopes](create-an-api-key.md#create-an-api-key-with-oauth-scopes-from-the-developer).
+   
+2. Ask the merchant to share the created API key and client ID with you.
+
+## Step 2 (Optional): Prepare for app tracking
+App tracking is optional. To track a self-hosted app, you need to use the following when setting up the authorisation assertion grant flow for the app:
+
+* The API key from the merchant
+* The client ID of a partner-hosted app
+
+> **Note:** The client ID that you receive from the merchant cannot be used to track a self-hosted app. If you want to track a self-hosted app, you need to use the client ID of a partner-hosted app instead of the client ID from the merchant.
+
+To prepare for tracking a self-hosted app:
+1. [Create a partner-hosting app](../create-a-partner-hosted-app.md).
+2. When setting up the authorisation assertion grant flow, make sure to use the client ID of the partner-hosted app instead of the client ID from the merchant. 
+
+## Next task
+* [Set up authorisation assertion grant](../../set-up-app-authorisation/set-up-authorisation-assertion-grant.md)
+
+## Related API reference
+* [OAuth2 API Reference](../../../../authorization.md)

oauth-api/images/check-integrations-in-my.zettle.com.png

@@ -0,0 +1,75 @@
+Create an API key
+======
+
+An API key is used in the authorisation assertion grant flow for an app. It must be created by a Zettle merchant in their my.zettle.com.
+
+If you're developer of a self-hosted app, share this guide with the merchant that will use the app.
+
+* [Create an API key with a link from the developer](#create-an-api-key-with-a-link-from-the-developer)
+* [Create an API with OAuth scopes from the developer](#create-an-api-key-with-oauth-scopes-from-the-developer)
+
+## Prerequisites
+* You are a Zettle merchant and have an account at my.zettle.com.
+* You have a link or OAuth scopes from the developer of the app that you will use.  The OAuth scopes are permissions that you give to the developer to access your Zettle account data. 
+
+## Create an API key with a link from the developer
+
+1. Open the link from the developer.
+
+2. Enter your Zettle account password.
+   
+3. Review the information and click **Create key**. A client ID will be created together with the API key.
+       
+   <img id="create-API-keys-from-the-deep-link" src="../../../images/create-API-keys-from-the-deep-link.png" alt="This screenshot shows the dialog that is started after clicking a deep link for creating API keys. You can find the Create key button in the lower right corner of the dialog.">       
+    
+4. On the Create API key page, click **Copy key**. Keep the API key and the client ID as secret somewhere safe.
+       
+   <img id="copy-key" src="../../../images/copy-key.png" alt="This screenshot shows the dialog where you can copy the API key and save it for later use. You can find the Copy key button in the lower right corner of the dialog.">
+    
+5. Share the API key and client ID with the developer who sent you the link.
+    
+   The created key is shown in the list of keys. After the integration starts working with the key, the Last used column will show the last time the integration accessed your Zettle data. 
+       
+   <img id="available-API-keys" src="../../../images/available-API-keys.png" alt="This screenshot shows the dialog where you can see a list of created API keys and their scopes.">
+
+## Create an API key with OAuth scopes from the developer
+
+1. Go to [my.zettle.com](https://my.zettle.com/) and log in to your account. 
+
+2. On the left panel, click **Integrations**.
+
+   <img id="check-integrations-in-my.zettle.com" src="../../../images/check-integrations-in-my.zettle.com.png" alt="This screenshot shows my zettle.com where you can find the Integrations link in the lower left corner of the left navigation menu.">
+ 
+3. Under the Integration tools section, click **API Keys**.
+
+   <img id="API-keys-in-Integration-tools" src="../../../images/API-keys-in-Integration-tools.png" alt="This screenshot shows the Integrations page where you can find the API keys link in the lower left corner of the left navigation menu on the page.">
+       
+4. Click **Create API Key**.
+   
+   <img id="create-API-key-dialog" src="../../../images/create-API-key-dialog.png" alt="This screenshot shows the Available API keys page where you can find the Create API key button in the upper right corner before the available API keys list on the page.">
+   
+5. Give a name to your key. Keep it short and descriptive. One good practice is to use the integration name as the key name.
+
+6. Select the OAuth scopes that the developer provided. The OAuth scopes are permissions that you give to the developer to access your Zettle account data.
+    
+7. Click **Create key**. A client ID will be created together with the API key.
+ 
+   <img id="select-scopes-create-API-keys-dialog" src="../../../images/select-scopes-create-API-keys-dialog.png" alt="This screenshot shows the dialog where you can select scopes for the API key that you will create. You can find the Create key button in the lower right corner of the dialog.">
+   
+8. Confirm your password.
+
+9. On the Create API key page, click **Copy key**. Keep the API key and the client ID as secret somewhere safe. 
+ 
+   <img id="copy-key" src="../../../images/copy-key.png" alt="This screenshot shows the dialog where you can copy the API key and save it for later use. You can find the Copy key button in the lower right corner of the dialog.">
+   
+10. Share the API key and client ID with the developer.
+        
+    The created key is shown in the list of keys. After the integration starts working with the key, the Last used column will show the last time the integration accessed your Zettle data. 
+ 
+    <img id="available-API-keys" src="../../../images/available-API-keys.png" alt="This screenshot shows the Available API keys page where you can see a list of created API keys.">
+    
+## Related task
+* [Create a self-hosted app](create-a-self-hosted-app.md)
+
+## Related API reference
+None

oauth-api/images/choose-the-app-that-needs-a-new-client-secret.png

@@ -0,0 +1,52 @@
+Set up authorisation assertion grant
+===
+
+To build a self-hosted app with APIs, you need to set up the authorisation assertion grant flow for the app using an API key. An API key is a JSON web token (JWT) assertion. 
+
+* [Prerequisites](#prerequisites)
+* [Step 1: Retrieve an access token from an API key](#step-1-retrieve-an-access-token-from-an-api-key)
+* [Step 2: Generate a new access token from the API key](#step-2-generate-a-new-access-token-from-the-api-key)
+* [Previous task](#previous-task)
+* [Related API reference](#related-api-reference)
+
+## Prerequisites
+* You have an account for the [Developer Portal](https://developer.zettle.com/). If you don't have an account, [sign up for a developer account](../../../get-started/user-guides/sign-up-for-a-developer-account.md).
+
+* You have an API key and a client ID for the app. If you don't have any, [create a self-hosted app](../create-an-app/create-a-self-hosted-app).
+
+## Step 1: Retrieve an access token from an API key
+To retrieve a short-lived access token from the API key, include the API key and the client ID in the following request.
+> **Note:** If you plan to track the app later on, [use the client ID of a partner-hosting app instead of the client ID from the merchant](../create-an-app/create-a-self-hosted-app/create-a-self-hosted-app.md#step-2-optional-prepare-for-app-tracking).
+   
+   ```
+    curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&client_id={client_ID}&assertion={API_key}" https://oauth.zettle.com/token
+   ```
+
+   Example:
+   
+   The following example retrieves an access token using the assertion grant flow. The response value `expires_in` is the remaining lifetime of the access token in seconds. The access token is valid for 7200 seconds.
+   
+   Request   
+   ```
+curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&client_id=6adde977-c34d-4de1-99b2-f6ed3e65431a&assertion=eyJraWQiOiIwIiwidHlwIjoiSl...y9V15QKjn4ZgKRumYb_ikw" https://oauth.zettle.com/token
+   ```
+   Response         
+   ```json
+       {
+           "access_token": "eyJraWQiOiIxNDQ0NzI3MTY0Njk4Iiwi...yZA",
+           "expires_in": 7200
+       }
+   ```
+
+> **Note:** If the API key is invalid or revoked by the merchant (Zettle account owner), the response returns error `invalid_grant`. You need to [get a new API key from the merchant](../create-an-app/create-a-self-hosted-app/create-a-self-hosted-app.md#step-1-get-an-api-key-from-a-zettle-merchant).
+
+
+## Step 2: Generate a new access token from the API key
+An access token is valid only for 7200 seconds. Use the same API key to generate a new access token, as in [Step 1: Retrieve an access token from an API key](#step-1-retrieve-an-access-token-from-an-api-key). 
+ 
+
+## Previous task
+* [Create a self-hosted app](../create-an-app/create-a-self-hosted-app)
+
+## Related API reference
+* [OAuth2 API Reference](../../../authorization.md)