Skip to content
Docs
About By Dawn Contact supportOpen By Dawn
  1. Get started
  2. Quickstart

Quickstart

In about five minutes you’ll make your first call to the By Dawn API: you’ll swap an API key for an access token, then list your organization’s projects. Pick your language on any code tab, and every page on this site follows. Rather not install anything? Run it in your browser.

Read down the steps. The code on the right follows along and highlights the lines each one explains.

  1. Create an API key

    Section titled “Create an API key”

    In By Dawn, open Settings › Organization › Security and find API keys. Name the key, and choose Board — read only for now. You can make a read & write key later, when your code needs to change things. Copy the key straight away: it starts with saw_live_, and By Dawn shows it only once.

    Only organization owners and admins can create keys. If that isn’t you, ask an admin for a read-only key. API keys walks through it.

  2. Set up your language

    Section titled “Set up your language”

    Each recipe is one file that uses only your language’s standard library, so there’s almost nothing to install.

    Node.js 22.6 or later. The script has no dependencies, but it’s typed from our OpenAPI document, so generate the types next to it:

    Terminal window
    npx openapi-typescript https://docs.bydawn.com/openapi/public.openapi.yaml -o saw-api.d.ts

    Regenerate them when the changelog records a change. npx tsx and bun run the file too.

    Save the recipe under its file name, set SAW_API_KEY to your key, and run the command that comes with it.

  3. Swap the key for an access token

    Section titled “Swap the key for an access token”

    Your key never travels with ordinary requests. Instead, the script sends it once to the accounts host and gets back an access token that lasts about 15 minutes. If a token leaks into a log, it expires on its own.

    A wrong or revoked key stops the script here with Token exchange failed: invalid_api_key.

    // 1. Exchange the API key for a short-lived access token.
    const exchange: Schemas['ApiKeyExchange'] = { apiKey };
    const tokenResponse = await fetch(`${ACCOUNTS_URL}/auth/token/api-key`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(exchange),
    });
    const token = (await tokenResponse.json()) as Schemas['AccessTokenData'] | Schemas['AccountsApiError'];
    if (!token.ok) throw new Error(`Token exchange failed: ${token.error}`);
    console.log(`Access token issued, valid for ${token.data.expiresInSeconds} seconds.`);

  4. Read your organization ID

    Section titled “Read your organization ID”

    Every API path starts with your organization’s ID, and you don’t need to look it up: the token carries it. A token is a JWT, three parts separated by dots, and the middle part holds its claims, including org_id.

    // 2. Read your organization ID from the token.
    // The token is a JWT; its `org_id` claim is the organization the key belongs to.
    const claims = JSON.parse(atob(token.data.accessToken.split('.')[1]!.replace(/-/g, '+').replace(/_/g, '/')));
    const orgId: string = claims.org_id;
    console.log(`Organization ID: ${orgId}`);

  5. Call the API

    Section titled “Call the API”

    Now send the token in an Authorization: Bearer … header and ask for your projects. Every answer has the same shape: ok says whether it worked, and the projects are in data. That shape is called the envelope, and every call on this site reads it the same way.

    The script prints the token’s lifetime, your organization ID and one line per project.

    // 3. Call the API with it: list the organization's projects.
    const projectsResponse = await fetch(`${WORKSPACE_URL}/orgs/${orgId}/projects`, {
      headers: { Authorization: `Bearer ${token.data.accessToken}` },
    });
    const projects = (await projectsResponse.json()) as Schemas['ProjectListData'] | Schemas['ApiError'];
    if (!projects.ok) throw new Error(`Listing projects failed: ${projects.error}`);
    

    console.log(`Your organization has ${projects.data.length} project(s):`);
    for (const project of projects.data) console.log(`  ${project.name}  (${project.id})`);

Run it in your browser

Section titled “Run it in your browser”

You can make the same first call without leaving this page. Paste your key and run the TypeScript Quickstart: your browser swaps the key and lists your projects, with the same code our CI runs. Try it in your browser explains what the page does with your key.

Try it with your organization

How this works

Connect once and run this recipe live against the By Dawn API.

Your key stays in this tab and goes only to By Dawn. Use a read-only key in a test organization.

▶ Run quickstart.tsThe same code CI runs, in your browser
Connect your organization above to run it.

Next

Section titled “Next”