Skip to content

Public API edits [DOC-1232] #7864

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 1 commit into from
Sep 2, 2025
Merged

Public API edits [DOC-1232] #7864

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
24 changes: 12 additions & 12 deletions src/api/public-api/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
title: Public API
plan: papi
---
The Segment Public API helps you manage your Segment workspaces and its resources. You can use the API to perform CRUD (create, read, update, delete) operations at no extra charge. This includes working with resources such as Sources, Destinations, Warehouses, Tracking Plans, and the Segment Destinations and Sources Catalogs. The Public API is available to Team and Business Tier customers.
The Segment Public API helps you manage your Segment workspaces and its resources. You can use the API to perform CRUD (create, read, update, and delete) operations at no extra charge. This includes working with resources such as Sources, Destinations, Warehouses, Tracking Plans, and the Segment Destinations and Sources Catalogs. The Public API is available to Team and Business Tier customers.

All CRUD endpoints in the API follow REST conventions and use standard HTTP methods. Different URL endpoints represent different resources in a workspace.

Expand All @@ -14,7 +14,7 @@ All CRUD endpoints in the API follow REST conventions and use standard HTTP meth
%}

> success "Getting started with the Public API"
> If your application is built in Javascript / Typescript, Go, Java, or Swift, check out [Segment's Public API SDKs](https://docs.segmentapis.com/tag/Getting-Started#section/Install-and-use-an-SDK){:target="_blank"}.
> If your application is built in JavaScript, Typescript, Go, Java, Swift, or C#, check out [Segment's Public API SDKs](https://docs.segmentapis.com/tag/Getting-Started#section/Install-and-use-an-SDK){:target="_blank"}.

## Config API vs Public API
The Public API includes the following benefits over the Config API:
Expand All @@ -28,24 +28,24 @@ The Public API includes the following benefits over the Config API:
| Improved architecture | The Public API is built with improved security, checks for authentication, authorization, input validation, HTTPS exposed services, auto-scaling, and more in mind. |
| Cleaner mapping | The Public API uses unique IDs for reference, in place of slugs in the Config API. Unique IDs are, by design, unique. |
| Available in Europe | The Public API is accessible to both US and EU-based workspaces. | |
| Increased reliability | The Public API features more stable endpoints, and a 99.8% success rate |
| Increased reliability | The Public API features more stable endpoints, and a 99.8% success rate. |

## Create a Public API token

> info "Only Workspace Owners can create a Public API token"
> Only users with the Workspace Owner role can create a Public API token. For more information about roles, see Segment's [Roles](/docs/segment-app/iam/roles/) documentation.
> Only users with the **Workspace Owner** role can create a Public API token. For more information about roles, see Segment's [Roles](/docs/segment-app/iam/roles/) documentation.

To create a Public API token in your Segment workspace:
1. Navigate to Settings > Workspace settings > Access Management > Tokens.
2. Click the **+ Create Token** button.
3. Create a description for the token and assign it either Workspace Owner or Workspace Member access.
1. Navigate to **Settings** > **Workspace settings** > **Access Management** > **Tokens**.
2. Click **+ Create Token**.
3. Create a description for the token and assign it either **Workspace Owner** or **Workspace Member** access.
4. Click **Create**.
5. Copy your workspace token somewhere secure and click **Done**.

To begin sending requests to the Public API, make sure to include the Public API Token into your HTTP requests with the `Authorization` Header and configured with `Bearer Token` and the value of the newly generated Public API token.
To begin sending requests to the Public API, include the Public API Token in your HTTP requests. Configure the `Authorization` Header as a `Bearer Token` with the value of the newly generated Public API token.


## API Token Security
## API token security

To enhance API token security, Segment partners with GitHub to prevent fraudulent use of exposed API tokens found in public git repositories. This helps to prevent malicious actors from using exposed tokens to perform unauthorized actions in your Segment workspace.

Expand All @@ -55,7 +55,7 @@ Learn more about [GitHub's secret scanning program](https://docs.github.com/en/d

## FAQs
#### What should I do if I see a notification that my token was exposed?
In most cases, identifying and revoking an exposed token takes seconds. Segment recommends you check the [audit trail](/docs/segment-app/iam/audit-trail/) to ensure no unauthorized actions were taken with the token.
In most cases, identifying and revoking an exposed token takes seconds. We recommend that you check the [audit trail](/docs/segment-app/iam/audit-trail/) to ensure no unauthorized actions were taken with the token.

#### How did my token get exposed?
Developers can accidentally commit tokens to public repositories, exposing them to the public. This can happen when developers use a token in a local development environment and forget to remove it before committing their code.
Expand All @@ -70,10 +70,10 @@ This feature is automatically enabled for all workspaces on Team or Business tie
If you see a CORS error, this means you're attempting to make a request to the Public API on the front-end. The Public API is used for server-side only. To get rid of the error, move all Public API requests to a server.

#### What User Role / Workspace permissions are required to generate Public API tokens?
Only [users that have a `Workspace Owner` role](https://segment.com/docs/segment-app/iam/roles/#global-roles) can create Public API Tokens.
Only [users that have a **Workspace Owner** role](/docs/segment-app/iam/roles/#global-roles) can create Public API Tokens.

## Troubleshooting
#### The `Update Schema Settings in Source` endpoint returns error for field `forwardingViolationsTo` and `forwardingBlockedEventsTo`
#### The `Update Schema Settings in Source` endpoint returns an error for fields `forwardingViolationsTo` and `forwardingBlockedEventsTo`
When you don't have a source to forward violations or blocked events to, then exclude the fields `forwardingViolationsTo` or `forwardingBlockedEventsTo` entirely from the request and the setting will be disabled.

`PATCH` endpoint : `https://api.segmentapis.com/sources/{sourceId}/settings`
Expand Down
Loading