You're in the right place! Segment documentation is now part of Twilio Docs. The content you are used to is still here—just in a new home with a refreshed look.

Authentication

Most destinations require some sort of authentication. Segment's destination interface provides details about how customers need to authenticate with your destination to send data or retrieve data for dynamic input fields.

Basic authentication

Basic authentication is useful if your destination requires a username and password to authenticate. These are values that only the customer and the destination know.

(success)

Success!

When scaffolding your integration, select Basic Auth from the auto-prompt or pass --template basic-auth.

1const authentication = {
2  // the 'basic' authentication scheme tells Segment to automatically
3  // include the `username` and `password` fields so you don't have to.
4  // Segment will automatically do base64 header encoding of the username:password
5  scheme: 'basic',
6
7  fields: {
8    username: {
9      label: 'Username',
10      description: 'Your username',
11      type: 'string',
12      required: true
13    },
14    password: {
15      label: 'password',
16      description: 'Your password.',
17      type: 'string',
18      required: true
19    }
20  },
21
22  // a function that can test the user's credentials
23  testRequest: (request) => {
24    return request('https://example.com/api/accounts/me.json')
25  }
26}
27
28const destination = {
29  // ...other properties
30  authentication,
31
32  extendRequest({ settings }) {
33    return {
34      username: settings.username,
35      password: settings.password
36    }
37  }
38}

Custom authentication

Custom authentication is the most commonly used authentication among Segment destinations. It's what most "API Key" based authentication should use. You'll likely need to define an extendRequest function to complete the authentication by modifying request headers with some authentication input fields.

1const authentication = {
2  // the 'custom' scheme doesn't do anything automagically for you, but let's you
3  // define the behavior through input fields and `extendRequest`.
4  // this is what most API key-based destinations should use
5  scheme: 'custom',
6
7  // a function that can test the user's credentials
8  testRequest: (request) => {
9    return request(`/accounts/me.json`)
10  },
11
12  // fields that are specific to authentication
13  fields: {
14    subdomain: {
15      type: 'string',
16      label: 'Subdomain',
17      description: 'The subdomain for your account, found in your user settings.',
18      required: true
19    },
20    apiKey: {
21      type: 'string',
22      label: 'API Key',
23      description: 'Found on your settings page.',
24      required: true
25    }
26  }
27}
28
29const destination = {
30  // ...other properties
31  authentication,
32  // we may explore a simple JSON representation that supports template strings
33  extendRequest: ({ settings }) => {
34    return {
35      prefixUrl: `https://${settings.subdomain}.example.com/api`,
36      headers: { Authorization: `Bearer ${settings.apiKey}` },
37      responseType: 'json'
38    }
39  }
40}

OAuth 2.0 managed

If your API supports OAuth 2.0, you can authenticate your destination's users with it.

1const authentication = {
2  // the 'oauth-managed' authentication scheme tells Segment use the
3  // oauth credentials and endpoint that you provide to authenticate users.
4  scheme: 'oauth-managed',
5}

When you receive access to the Developer Portal, find your integration, and navigate to the OAuth settings tab to configure the integration's OAuth details.