Merge pull request #6040 from segmentio/DOC-821

obtain OAuth access token [DOC-821]

Author: stayseesong

src/connections/oauth.md

@@ -67,14 +67,62 @@ Once you've connected your source to OAuth, you can enable it. To enable your so
 
 To disable your source from OAuth, turn the toggle off for **Enable OAuth**.
 
-<!-- ## Request the access token
-
-To request the access token, run:
-
-```
-./gentoken.sh -k <private-key.pem> -i <key_id> -a <oauth_app_id> | jq '.access_token'
-```
--->
+## Obtain the access token
+You can obtain an access token once you create an OAuth application and enable a source to OAuth.  
+
+Access tokens are only valid within a region. The supported regional authorization servers are: 
+* Oregon - `https://oauth2.segment.io`
+* Dublin - `https://oauth2.eu1.segmentapis.com`
+
+To obtain the access token:
+
+1. Create a JWT token with the header and payload as below:
+
+    Header
+    ```
+    {
+        "alg":"RS256", 
+        "typ":"JWT", 
+        "kid":"<<KID>>"
+    }
+    ```
+
+    Payload
+    ```
+    {
+        "iss":"<<ISS>>",
+        "sub":"<<SUB>>",
+        "aud":"<<AUD>>", 
+        "iat":"<<IAT>>",
+        "exp":"<<EXP>>",
+        "jti":"<<JTI>>"
+    }
+    ```
+
+    Field | Description 
+    ------------ | -------------
+    KID | The key ID of the public key in the OAuth application.
+    ISS | The identifier of the JWT issuer.
+    SUB | The OAuth application ID. 
+    IAT | The epoch time in seconds when the token was issued. 
+    EXP | The expiry time in seconds. This is expected to be valid only for a short duration under a minute. 
+    JTI | The unique identifer for the token. 
+
+2. Send a form-url-encoded `POST` request to the regional authorization server with the following parameters:
+    
+    ```
+    grant_type=client_credentials
+    client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
+    client_assertion=<<JWT>>
+    scope=<<SCOPE>>
+    ```
+
+    Field | Description
+    ----- | ------------
+    JWT | The signed JWT token string from Step 1.
+    SCOPE | Scopes for which token is requested. See [supported scopes](#supported-scopes).
+
+To use the access token, see an example of how to use the access token in the [HTTP API source](). 
 
 ## Edit an OAuth application
 To edit an existing OAuth application: 

src/connections/sources/catalog/libraries/server/http-api/index.md

@@ -11,6 +11,10 @@ Segment has native [sources](/docs/connections/sources/) for most use cases (lik
 
 ### Authentication
 
+Choose between [basic authentication](#basic-authentication) and [OAuth](#oauth) to authenticate requests. 
+
+#### Basic authentication
+
 Authenticate to the Tracking API by sending your project's **Write Key** along with a request.
 Authentication uses HTTP Basic Auth, which involves a `username:password` that is base64 encoded and prepended with the string `Basic`.
 
@@ -19,6 +23,33 @@ In practice that means taking a Segment source **Write Key**,`'abc123'`, as the
 > info ""
 > Include a colon before encoding. While encoding the write key without a colon might work due to backward compatibility, this won't always be the case.  
 
+#### OAuth
+[Obtain the access token](/docs/connections/oauth/) from the Authorization Server specific to the region. 
+
+Include the access token in the Authorization header as a Bearer token along with your project's write key in the payload of the request. For example, Authorization with Bearer token looks like:
+
+  ```
+  Authorization: Bearer <access token>
+  ```
+
+
+For example, to use the access token in the HTTP API Source, use `access_token` in the header and `write_key` in the payload. An example cURL request looks like: 
+
+```
+  curl --location 'https://api.segment.io/v1/track' \
+  --header 'Content-Type: application/json' \
+  --header 'Authorization: Bearer <access token>' \
+  --data-raw '{
+      "event": "happy-path-a3ef8a6f-0482-4694-bc4d-4afba03a0eab",
+      "email": "[email protected]",
+      "messageId": "58524f3a-3b76-4eac-aa97-d88bccdf4f77",
+      "userId": "123",
+      "writeKey": "DmBXIN4JnwqBnTqXccTF0wBnLXNQmFtk"
+  }
+```
+
+You can reuse the access token until the expiry period specified on the OAuth application. 
+
 ### Content-Type
 
 To send data to Segment's HTTP API, a content-type header must be set to `'application/json'`.