> ## 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.

## Creating an API Key

**1. Open your workspace settings**

Navigate to your workspace dashboard and click **Settings** in the sidebar.

**2. Go to API Keys**

Click on **API Keys** in the settings menu.

**3. 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).

**4. Copy your key**

Your API key will only be shown once. Copy it and store it securely.

### 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](https://docs.marblecms.com/api/introduction.md#authentication) for the full scope reference and the `403 "API key missing required scope: <scope>"` response.

<video autoPlay loop muted playsInline controls>
  <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" />
</video>

> [!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](https://docs.marblecms.com/api/rate-limits.md) 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.

## Authentication

Include your API key in the `Authorization` header:

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

> [tab] 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);
> ```

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.

## Available Resources

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

## Next Steps

> [card] [Pagination](https://docs.marblecms.com/api/pagination.md)
>
> Learn how to paginate through large result sets.

> [card] [Rate Limits](https://docs.marblecms.com/api/rate-limits.md)
>
> Understand API rate limiting and best practices.

> [card] [TypeScript Types](https://docs.marblecms.com/api/types.md)
>
> Use our TypeScript definitions for type-safe development.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.