Authentication

Programmatic access to the Config API happens using personal access tokens. When authenticating with a personal access token, you will have access to any resources owned by the user who created that token.

Create a Personal Access Token

Create a personal access token with your Segment account email and password. If you do not have a password due to SSO, you can create one through the reset password web flow.

Warning: Workspace Owners

Note that only workspace owners can create personal access tokens. Workspace read-only users can not.

By default a personal access token has full access to the workspace owned by the user who creates it.

$ USER=me@example.com
$ PASS=<your Segment password>
$ WORKSPACE=<your Segment workspace>

$ curl \
  -X POST \
  -d "{'access_token': {'description': 'my access token', 'scopes': 'workspace', 'workspace_names': ['workspaces/$WORKSPACE']}}" \
  -u "$USER:$PASS" \
  https://platform.segmentapis.com/v1beta/access-tokens

Example Response:

{
  "name": "access-tokens/5",
  "description": "my access token",
  "scopes": "workspace",
  "create_time": "2018-10-12T22:36:39Z",
  "token": "qiTgISif4zprgBb_5j4hXfp3qhDbxrntWwwOaHgAMr8.gg9ok4Bk7sWlP67rFyXeH3ABBsXyWqNuoXbXZPv1y2g",
  "workspace_names": [
    "workspaces/myworkspace"
  ]
}

You can limit this to read-only access by specifying a workspace:read scope.

$ USER=me@example.com
$ PASS=<your Segment password>
$ WORKSPACE=<your Segment workspace>

$ curl \
  -X POST \
  -d "{'access_token': {'description': 'my access token', 'scopes': 'workspace:read', 'workspace_names': ['workspaces/$WORKSPACE']}}" \
  -u "$USER:$PASS" \
  https://platform.segmentapis.com/v1beta/access-tokens

Example Response:

{
  "name": "access-tokens/6",
  "description": "my access token",
  "scopes": "workspace:read",
  "create_time": "2018-10-12T22:36:39Z",
  "token": "qiTgISif4zprgBb_5j4hXfp3qhDbxrntWwwOaHgAMr8.gg9ok4Bk7sWlP67rFyXeH3ABBsXyWqNuoXbXZPv1y2g",
  "workspace_names": [
    "workspaces/myworkspace"
  ]
}

Warning: Secret Token

Note that you can not retrive the plain-text token later, so you should save it in a secret manager. If you lose the token you can generate a new one.

Use a Personal Access Token

Now that you have a personal access token, you can use this token to access the Config API by setting it in the Authorization header of your requests, for example:

$ ACCESS_TOKEN=qiTgISif4zprgBb_5j4hXfp3qhDbxrntWwwOaHgAMr8.gg9ok4Bk7sWlP67rFyXeH3ABBsXyWqNuoXbXZPv1y2g

$ curl \
  -X GET \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://platform.segmentapis.com/v1beta/workspaces

Example response:

{
  "workspaces": [
    {
      "name": "myworkspace",
      "display_name": "My Space",
      "id": "e5bdb0902b",
      "create_time": "2018-08-08T13:24:02.651Z"
    }
  ]
}

Scopes

You cannot use access tokens created with the workspace:read scope to create or update resources. If you do so, you’ll get the following error:

{
  "error": "insufficient scope",
  "code": 7
}

See Config API Errors for error codes.


If you have any questions, or see anywhere we can improve our documentation, please let us know!