Skip to content

Add docs on including writeKey in the body to authenticate #6147

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 1, 2024
Merged

Add docs on including writeKey in the body to authenticate #6147

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ee5ba2e
Remove basic auth
Feb 28, 2024
67985d2
Remove basic auth
Feb 28, 2024
adee552
Remove basic auth
Feb 28, 2024
4264fd5
Add basic auth with writekey auth
Feb 29, 2024
7776f02
Add basic auth with writekey auth
Feb 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 35 additions & 11 deletions src/connections/sources/catalog/libraries/server/http-api/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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=='`.

Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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"
}
```

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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"
}
```

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -422,7 +445,8 @@ POST https://api.segment.io/v1/identify
"Mixpanel": true,
"Kissmetrics": true,
"Google Analytics": false
}
},
"writeKey": "YOUR_WRITE_KEY"
}
```

Expand Down