Merge pull request #6147 from segmentio/niall/http_writekey

Add docs on including writeKey in the body to authenticate

Author: niallzato

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

@@ -11,12 +11,28 @@ 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
+Choose between [writeKey authentication](#writeKey-authentication), [basic authentication](#basic-authentication) and [OAuth](#oauth) to authenticate requests. 
 
+#### writeKey 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`.
+The authentication writeKey should be sent as part of the body of the request. This will be encrypted over https.
+
+```
+  curl --location 'https://api.segment.io/v1/track' \
+  --header 'Content-Type: application/json' \
+  --data-raw '{
+      "event": "happy-path-a3ef8a6f-0482-4694-bc4d-4afba03a0eab",
+      "email": "[email protected]",
+      "userId": "123",
+      "writeKey": "DmBXIN4JnwqBnTqXccTF0wBnLXNQmFtk"
+  }'
+```
+
+> info ""
+> For this auth type, you do not need to set any authentication header. 
+
+#### Basic authentication
+Basic authentication uses HTTP Basic Auth, which involves a `username:password` that is base64 encoded and prepended with the string `Basic`.
 
 In practice that means taking a Segment source **Write Key**,`'abc123'`, as the username, adding a colon, and then the password field is left empty. After base64 encoding `'abc123:'` becomes `'YWJjMTIzOg=='`; and this is passed in the authorization header like so: `'Authorization: Basic YWJjMTIzOg=='`.
 
@@ -105,7 +121,8 @@ POST https://api.segment.io/v1/identify
   "context": {
     "ip": "24.5.68.47"
   },
-  "timestamp": "2012-12-02T00:30:08.276Z"
+  "timestamp": "2012-12-02T00:30:08.276Z",
+  "writeKey": "YOUR_WRITE_KEY"
 }
 ```
 This call is identifying the user by their unique User ID (the one you know them by in your database) and labeling them with `email`, `name`, and `industry` traits.
@@ -145,7 +162,8 @@ POST https://api.segment.io/v1/track
   "context": {
     "ip": "24.5.68.47"
   },
-  "timestamp": "2012-12-02T00:30:12.984Z"
+  "timestamp": "2012-12-02T00:30:12.984Z",
+  "writeKey": "YOUR_WRITE_KEY"
 }
 ```
 
@@ -178,7 +196,8 @@ POST https://api.segment.io/v1/page
 {
   "userId": "019mr8mf4r",
   "name": "Tracking HTTP API",
-  "timestamp": "2012-12-02T00:31:29.738Z"
+  "timestamp": "2012-12-02T00:31:29.738Z",
+  "writeKey": "YOUR_WRITE_KEY"
 }
 ```
 The `page` call has the following fields:
@@ -210,7 +229,8 @@ POST https://api.segment.io/v1/screen
 {
   "userId": "019mr8mf4r",
   "name": "Tracking HTTP API",
-  "timestamp": "2012-12-02T00:31:29.738Z"
+  "timestamp": "2012-12-02T00:31:29.738Z",
+  "writeKey": "YOUR_WRITE_KEY"
 }
 ```
 
@@ -249,7 +269,8 @@ POST https://api.segment.io/v1/group
     "industry": "Technology",
     "employees": 420
   },
-  "timestamp": "2012-12-02T00:31:38.208Z"
+  "timestamp": "2012-12-02T00:31:38.208Z",
+  "writeKey": "YOUR_WRITE_KEY"
 }
 ```
 The `group` call has the following fields:
@@ -282,7 +303,8 @@ POST https://api.segment.io/v1/alias
 {
   "previousId": "39239-239239-239239-23923",
   "userId": "019mr8mf4r",
-  "timestamp": "2012-12-02T00:31:29.738Z"
+  "timestamp": "2012-12-02T00:31:29.738Z",
+  "writeKey": "YOUR_WRITE_KEY"
 }
 ```
 The `alias` call has the following fields:
@@ -365,6 +387,7 @@ POST https://api.segment.io/v1/batch
       "timestamp": "2015-2-02T00:30:12.984Z"
     }
   ],
+  "writeKey": "YOUR_WRITE_KEY",
   "context": {
     "device": {
       "type": "phone",
@@ -422,7 +445,8 @@ POST https://api.segment.io/v1/identify
     "Mixpanel": true,
     "Kissmetrics": true,
     "Google Analytics": false
-  }
+  },
+  "writeKey": "YOUR_WRITE_KEY"
 }
 ```