Skip to content

Commit

Permalink
Add basic API tutorials (#7433)
Browse files Browse the repository at this point in the history
- Add tutorial for generating API keys
- Add basic tutorial for creating and listing projects
- Add unpublished draft guide for projects-related APIs

---------

Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
  • Loading branch information
shanamatthews and getsantry[bot] authored Aug 8, 2023
1 parent 21ceae3 commit ee59760
Show file tree
Hide file tree
Showing 8 changed files with 545 additions and 1 deletion.
66 changes: 66 additions & 0 deletions src/api/guides/create-auth-token.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
title: "Tutorial: Create a Sentry Authentication Token"
sidebar_order: 8
---

To use Sentry's APIs, you must have an authentication token. This tutorial walks you through creating an organizational auth token through an internal integration. Sentry recommends using organizational auth tokens whenever possible, as they aren't linked to specific user accounts.

See our documentation on [authentication](/api/auth/) to learn more about the different types of authentication tokens available.

## Prerequisites

- A Sentry account with an organization-level role of Manager or Admin.

## Create an Internal Integration

[Internal integrations](/product/integrations/integration-platform/internal-integration/) are used to create custom Sentry integrations for your organization. They can also be used to create and manage your organization auth tokens.

1. Open [sentry.io](https://sentry.io/)

1. Click "Settings" in the left menu to open the **Organization Settings** page.

1. Click "Custom Integrations" in the left side panel to create a new internal integration and org-level auth token.

1. Press the "Create New Integration" button.

1. Make sure "Internal Integration" is selected in the modal and press "Next".

1. Enter a name for your integration.

<div style="position: relative; padding-bottom: calc(66.66666666666666% + 41px); height: 0; width: 100%">
<iframe
src="https://demo.arcade.software/tn7T3kQtjpIZEAfAe6ep?embed"
frameborder="0"
loading="lazy"
webkitallowfullscreen
mozallowfullscreen
allowfullscreen
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;color-scheme: light;"
title="Create internal integration"
></iframe>
</div>

## Create a API Authentication Token

1. Under "Permissions" select the permissions required for the APIs you wish to call.

Each API endpoint docs page lists the required permissions, in the "Scopes" section. For example, the [Create a New Project](/api/projects/create-a-new-project/) endpoint requires project:write permissions or higher.

1. Click "Save Changes".

1. Scroll down to the bottom of the page and copy the generated token under "Tokens".

<div style="position: relative; padding-bottom: calc(66.63414634146342% + 41px); height: 0; width: 100%">
<iframe
src="https://demo.arcade.software/fd21PKLR6Imy6ntQ1Dhh?embed"
frameborder="0"
loading="lazy"
webkitallowfullscreen
mozallowfullscreen
allowfullscreen
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;color-scheme: light;"
title="Set token permissions (copy)"
></iframe>
</div>

Keep your auth token around on your clipboard or in an environment variable to use in API calls.
5 changes: 5 additions & 0 deletions src/api/guides/index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
title: API Guides
---

<PageGrid />
107 changes: 107 additions & 0 deletions src/api/guides/projects-guide.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
---
title: "Guide: Create and Configure a Project with the Sentry API"
sidebar_order: 8
---

This guide provides a high-level overview of how to use Sentry's API to create a new project and configure advanced settings on that project. It assumes a intermediate level of familiarity with Sentry and Sentry's APIs.

For a beginner-friendly tutorial, check out the [Create and List Teams with the Sentry API](/api/guides/teams-tutorial/) tutorial.

Endpoints used in this guide:

- [Create a New Project](/api/projects/create-a-new-project/)
- [Update an Inbound Data Filter](/api/projects/update-an-inbound-data-filter/)
- [Update a Project](/api/projects/update-a-project/)
- [Update a Client Key](/api/projects/update-a-client-key/)
- [Add a Team to a Project](/api/projects/add-a-team-to-a-project/)

## Prerequisites

- One or more Sentry authentication tokens with the required scope(s) for each endpoint.

> If you don't have an authentication token, follow the [Create a Sentry Authentication Token](/api/guides/create-auth-token) tutorial to create an organization auth token.
We recommend using a free [Sentry developer account](https://sentry.io/pricing/) for this tutorial.

## Create a Project

To programmatically create a new project in Sentry, use the [Create a New Project](/api/projects/create-a-new-project/) endpoint.

### Auth scope

This endpoint requires an auth token with a scope of `project:write` or higher.

### Required parameters

As with most Project APIs, you must specify the `organization_slug` and `team_slug` for an existing organization and team to add the project to to as path parameters in the API call. You must also specify the project name, `name`, as a query parameter.

### Other parameters

If you don't specify a `platform`, the default platform is JavaScript. The `default_rules` param specifies whether the default alert rule (users are notified for every new issue) should be turned on for the project. Today, other than this setting, alert rules can only be modified or created through the Sentry UI.

Here's an example cURL call that shows creating a new project with the following parameters:

- Path Parameters

- `organization_slug`: `test-org`
- `team_slug`: `test-team`

- Query Parameters
- `name`: `proj-name`
- `platform`:
- `default_rules=false` =

```cURL
url https://sentry.io/api/0/teams/{organization_slug}/{team_slug}/projects/ \
-H 'Authorization: Bearer <auth_token>' \
-H 'Content-Type: application/json'
```

## Add an Inbound Data Filter to the Project

- [Update an Inbound Data Filter](https://docs.sentry.io/api/projects/update-an-inbound-data-filter/) endpoint
- Path Parameters
- `organization_slug`
- `team_slug`
- `filter_id`
- Query Parameters
- `active`
- `subfilters`

## Add a Custom Inbound Data Filter to the Project

- [Update a Project](https://docs.sentry.io/api/projects/update-a-project/) endpoint
- Path Parameters
- `organization_slug`
- `team_slug`
- Query Parameters
- `options`
{
options: {
filters:react-hydration-errors: true,
filters:blacklisted_ips: "127.0.0.1\n192.168. 0.1"
filters:releases: "[!3]\n4"
filters:error_messages: "TypeError*\n*ConnectionError\*"
}
}

## Update the DSN Client Key of the Project's Rate Limits

- [Update a Client Key](https://docs.sentry.io/api/projects/update-a-client-key/) endpoint
- Path Parameters
- `organization_slug`
- `team_slug`
- `key_id`
- Query Parameters
- `rateLimit`
{
"rateLimit": {
"window": 7200, // time in seconds
"count": 1000 // error cap
}
}

## Add a Team to the Project

- [Add team to a project](https://docs.sentry.io/api/projects/add-a-team-to-a-project/) endpoint
- [Remove team from project](https://docs.sentry.io/api/projects/delete-a-team-from-a-project/) endpoint
Loading

1 comment on commit ee59760

@vercel
Copy link

@vercel vercel bot commented on ee59760 Aug 8, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Successfully deployed to the following URLs:

sentry-docs – ./

sentry-docs-git-master.sentry.dev
docs.sentry.io
sentry-docs.sentry.dev

Please sign in to comment.