# Try it in your browser

> Make live API calls and run the recipes from this site with your own API key, and how the recipes are written.

You can call the By Dawn API without leaving this site, which is the quickest way to see what an
operation really returns. Connect your organization once, below, and then:

- **In the [API reference](https://docs.bydawn.com/reference/),** every operation has a **Try it** button that opens a
  console for it. The URL already points at your organization, so there's no `{orgId}` to fill
  in. ID fields have a **Choose** button that lists your own projects, tickets, columns, cycles
  and people. Request bodies start from the reference's example with your IDs swapped in. The
  answer shows its status, how long it took, its `X-Correlation-Id` and the JSON.
- **On the [Quickstart](https://docs.bydawn.com/developers/quickstart/#run-it-in-your-browser) and each recipe page,** **Run
  this in your browser** runs the code on the page and shows what it printed, plus every request
  it made.

> The Try it credential panel is on the [web version of this page](https://docs.bydawn.com/developers/try-it/).

## Which credential to use

- **An API key** (`saw_live_…`) is the simplest. The page swaps it for an access token, as
  [Authentication](https://docs.bydawn.com/developers/authentication/) describes, and renews the token before it expires.
- **An access token** works too. The page uses it as it is until it expires, about 15 minutes
  after it was issued, and then you paste a fresh one.

Use a key made for trying things out: a **Board — read only** key in a **test organization** is
the safest. A few operations, like deleting a ticket, refuse API keys altogether. The console
tells you when that happens, and a signed-in member's access token works for those.

## What a write does

Anything other than a `GET` changes real data in your organization, so **Send request** asks
first: the button turns red and names your organization, and only a second click sends it.
`DELETE` operations also warn that they can't be undone. When you create something, such as a
ticket, its ID becomes the default for the next operation that needs one.

## Where your credential goes

- **It stays in this tab.** The page keeps it in the browser's session storage, so other tabs
  never see it and closing the tab deletes it. **Disconnect** deletes it at once, along with any
  IDs the console remembered.
- **It goes only to By Dawn.** Your key goes only to the accounts host (`accounts.dev.sawrun.com`) to
  be exchanged, and your access token only to the workspace host (`workspace.dev.sawrun.com`).
  There's no proxy, and this site has no server that could keep it.
- **The calls are yours.** They count against your key's
  [rate limits](https://docs.bydawn.com/developers/pagination-and-rate-limits/#rate-limits), and anything they create shows
  your key as its author.

[Authentication](https://docs.bydawn.com/developers/authentication/) tells you to keep keys out of web pages. That's about
apps you ship, where every visitor could read the key. Here the key is yours, in your own browser.

## How the recipes are written

Every code sample on this site is a **recipe**: one complete program, in one file, that does one
job. Each recipe exists in TypeScript, Python, Java, C#, Go and cURL, and uses only that
language's standard HTTP and JSON libraries (plus Jackson for JSON in Java). There's no By Dawn SDK to
install: copy the file, set `SAW_API_KEY` and run it.

They all start the same way. A recipe swaps your key for an access token, reads your organization
ID from the token, and sends the token with each call. It checks every response and turns a
failure into an error that carries the HTTP status and the
[error slug](https://docs.bydawn.com/developers/responses-and-errors/). The recipe that pages through tickets also waits and
retries once if it hits a [rate limit](https://docs.bydawn.com/developers/pagination-and-rate-limits/#rate-limits). Each one
exchanges the key only once, because it's done long before the token expires. A long-running
integration has to exchange again, as [Authentication](https://docs.bydawn.com/developers/authentication/#exchange-a-key-for-an-access-token)
explains.

**Every recipe runs in our CI against the live API**, in every language, on every change and
every night. So the code you copy here works, and each page's "What you'll see" is what it really
prints.

## What a recipe run does

**Run** doesn't copy the recipe or imitate it. Your browser runs the recipe's own code, the code
CI runs, with only its TypeScript types removed. Your credential stands in for `SAW_API_KEY`, and
the fields above the button stand in for the recipe's other settings. Under the output you'll find
every request it made, with its status, its duration and its `X-Correlation-Id`. Quote that ID if
you ask us about a call that failed.

If you pasted an access token rather than a key, the recipe still asks to exchange a key. The page
answers that request itself, with your token, and the request list says so.

Source: https://docs.bydawn.com/developers/try-it/