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

# API Authentication

> Create a public or private API key, choose the right scopes, and make your first authenticated request to the Marble REST API in minutes.

## Quick Start

Make your first API request in seconds! Copy and paste this command into your terminal:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -H "Authorization: YOUR_API_KEY" https://api.marblecms.com/v1/posts
```

<Tip>Replace `YOUR_API_KEY` with an API key from your Marble dashboard.</Tip>

## Creating an API Key

<Steps>
  <Step title="Open your workspace settings">
    Navigate to your workspace dashboard and click **Settings** in the sidebar.
  </Step>

  <Step title="Go to API Keys">Click on **API Keys** in the settings menu.</Step>

  <Step title="Create a new key">
    Click **Create API Key**, give it a descriptive name (e.g., "Production
    Website"), and choose a key type and permissions (see below).
  </Step>

  <Step title="Copy your key">
    Your API key will only be shown once. Copy it and store it securely.
  </Step>
</Steps>

### Choosing a key type

* **Public key** (`mpk_…`) — read-only. Pick this for client-side code, static site generators, or anywhere the key may be observed. Public keys can only hold the read scopes: `posts_read`, `authors_read`, `categories_read`, `tags_read`, `media_read`, and `fields_read`.
* **Private key** (`msk_…`) — full access. Use it from trusted server-side environments. Private keys can additionally hold write scopes (`posts_write`, `authors_write`, `categories_write`, `tags_write`, `media_write`, `fields_write`) and `posts_read_drafts` for reading unpublished posts.

### Choosing permissions

When creating a key, the **Permissions** section lists every available scope. Grant only the scopes the integration needs — for example, a website that lists published posts and authors needs `posts_read` and `authors_read` and nothing else. To read drafts via `GET /v1/posts?status=draft` or `?status=all`, create a private key and include the `posts_read_drafts` scope; otherwise the request returns `403 Forbidden`.

See [Authentication](/api/introduction#authentication) for the full scope reference and the `403 "API key missing required scope: <scope>"` response.

<Frame>
  <video autoPlay loop muted playsInline controls className="w-full aspect-video rounded-xl">
    <source src="https://mintcdn.com/marblecms/VyF0azMu6yWtXGXT/images/api-key-creation.mp4?fit=max&auto=format&n=VyF0azMu6yWtXGXT&q=85&s=92e76a0c18f0af2391b66280e4813b7f" type="video/mp4" data-path="images/api-key-creation.mp4" />
  </video>
</Frame>

<Warning>
  API keys should be kept secure. Public keys are scoped to read operations
  only, but exposing them in client-side code can lead to your [rate
  limits](/api/rate-limits) being consumed by others. Never ship a private key
  to the client — it can write to your workspace and read drafts. We recommend
  performing API requests on the server-side whenever possible.
</Warning>

## Authentication

Include your API key in the `Authorization` header:

<Tabs>
  <Tab title="cURL">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -H "Authorization: YOUR_API_KEY" https://api.marblecms.com/v1/posts
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch("https://api.marblecms.com/v1/posts", {
      headers: {
        Authorization: "YOUR_API_KEY",
      },
    });
    const data = await response.json();
    console.log(data);
    ```
  </Tab>
</Tabs>

Alternatively, use the `key` query parameter:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.marblecms.com/v1/posts?key=YOUR_API_KEY"
```

<Note>
  The `Authorization` header method is recommended for security. Query
  parameters may appear in server logs.
</Note>

## Available Resources

* **[Posts](/api-reference/posts/list-posts)**: List, get, create, update, or delete posts
* **[Authors](/api-reference/authors/list-authors)**: List, get, create, update, or delete authors
* **[Categories](/api-reference/categories/list-categories)**: List, get, create, update, or delete categories
* **[Tags](/api-reference/tags/list-tags)**: List, get, create, update, or delete tags
* **[Media](/api-reference/media/list-media-assets)**: List, get, upload, update, or delete media assets

## Next Steps

<CardGroup>
  <Card title="Pagination" icon="book-open" href="/api/pagination">
    Learn how to paginate through large result sets.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api/rate-limits">
    Understand API rate limiting and best practices.
  </Card>

  <Card title="TypeScript Types" icon="code" href="/api/types">
    Use our TypeScript definitions for type-safe development.
  </Card>
</CardGroup>