> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenotra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate requests to the Notra API using API keys.

Notra API requests are authenticated with API keys.

## How It Works

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -H "Authorization: Bearer YOUR_API_KEY" \
    "https://api.usenotra.com/v1/posts"
  ```

  ```typescript fetch theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.usenotra.com/v1/posts", {
    headers: {
      Authorization: `Bearer ${process.env.NOTRA_API_KEY}`,
    },
  });

  const data = await response.json();
  console.log(data);
  ```

  ```typescript SDK theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Notra } from "@usenotra/sdk";

  const notra = new Notra({
    bearerAuth: process.env["NOTRA_BEARER_AUTH"] ?? "",
  });

  const result = await notra.content.listPosts();
  console.log(result);
  ```
</CodeGroup>

| Name         | Type   | Scheme      | Environment Variable |
| ------------ | ------ | ----------- | -------------------- |
| `bearerAuth` | `http` | HTTP Bearer | `NOTRA_BEARER_AUTH`  |

## Create an API Key

1. Open your workspace dashboard.
2. Go to **API Keys** under **Developer**.
3. Click **Create API Key**.
4. Choose a name, resource permissions, and optional expiration.
5. Copy the key and store it securely.

<img src="https://mintcdn.com/notra/61y0WT4n5c9L1YWx/images/api/api-keys-light.webp?fit=max&auto=format&n=61y0WT4n5c9L1YWx&q=85&s=1fa24983d8adeb0523097591b1e698a5" alt="API Keys page in the Notra dashboard" className="block dark:hidden" width="2284" height="1518" data-path="images/api/api-keys-light.webp" />

<img src="https://mintcdn.com/notra/61y0WT4n5c9L1YWx/images/api/api-keys-dark.webp?fit=max&auto=format&n=61y0WT4n5c9L1YWx&q=85&s=3be3c3f0863ee159b243b13264fefb39" alt="API Keys page in the Notra dashboard" className="hidden dark:block" width="2284" height="1518" data-path="images/api/api-keys-dark.webp" />

API keys are powered by [Unkey](https://unkey.dev).

## Permissions

API keys can be scoped per resource. Grant **Read** when a key only needs to
fetch data, **Write** when it needs to create, update, or delete that resource,
and **None** when the key should not access the resource.

Available resources:

* Posts
* Brand identities
* Integrations
* Schedules
* Chats
* Skills

Legacy keys with the older `api.read` and `api.write` permissions continue to
work. New keys use the resource-specific scopes.

## Error Handling

<CodeGroup>
  ```typescript fetch theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const response = await fetch("https://api.usenotra.com/v1/posts", {
    headers: { Authorization: `Bearer ${process.env.NOTRA_API_KEY}` },
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(error.error); // e.g. "Missing or invalid API key"
  }
  ```

  ```typescript SDK theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Notra } from "@usenotra/sdk";
  import * as errors from "@usenotra/sdk/models/errors";

  const notra = new Notra({
    bearerAuth: process.env["NOTRA_BEARER_AUTH"] ?? "",
  });

  try {
    const result = await notra.content.listPosts();
    console.log(result);
  } catch (error) {
    if (error instanceof errors.NotraError) {
      console.log(error.message);
      console.log(error.statusCode);
      console.log(error.body);
    }
  }
  ```
</CodeGroup>

## Security Best Practices

<Warning>
  Treat API keys as secrets. Do not expose them in client-side code, public
  repositories, or logs.
</Warning>

<Tip>
  Store your key in a server-side environment variable such as `NOTRA_BEARER_AUTH`
  and make requests from your backend whenever possible.
</Tip>

If a key is exposed, delete it immediately by going to **API Keys** under the **Developer** section of your dashboard sidebar.