---
title: "Authentication"
description: "Authenticate Pallyy API requests with an API key, understand scopes for reading and writing, and restrict keys to specific social sets."
category: "getting-started"
emoji: "🔑"
order: 1
datePublished: "2026-08-20"
dateUpdated: "2026-08-20"
---

The Pallyy API is a REST API served over HTTPS. Every endpoint lives under a single base URL:

```
https://app.pallyy.com/api/v1
```

All requests are authenticated with an API key. Requests without a valid key receive a `401` response.

## API keys

API keys are created from your Pallyy account and always start with the `pallyy_` prefix. The full key is only shown once, when it is created, so store it somewhere safe. If you lose a key, revoke it and create a new one.

A few things to know about keys:

- You can have up to 10 active keys per account.
- Each key has a name, a set of scopes, and an optional social set restriction.
- Keys can be disabled or revoked at any time. Requests with a disabled or revoked key receive a `401` with the error code `api-key:invalid`.

## Authenticating requests

Pass your key as a bearer token in the `Authorization` header:

```bash
curl https://app.pallyy.com/api/v1/social-sets \
  -H "Authorization: Bearer pallyy_your_api_key"
```

Requests that send a body must also set `Content-Type: application/json`.

## Scopes

Every valid key can read. Scopes only gate writes: a key with no scopes is read-only.

| Scope | Grants |
| --- | --- |
| `post-sets:write` | Create and update post sets |
| `post-sets:publish` | Required on top of `post-sets:write` to create or update post sets with status `SCHEDULED`, meaning posts that will actually publish |
| `media:write` | Create media uploads |

Calling a write endpoint with a key that is missing the required scope returns a `403` with the error code `api-key:missing_scope`.

The split between `post-sets:write` and `post-sets:publish` exists so you can hand out keys that draft content without being able to publish it. A key with only `post-sets:write` can create and update drafts, but any attempt to schedule requires `post-sets:publish`.

## Social set restrictions

A key can be restricted to one or more social sets. A restricted key:

- Only sees its allowed sets when listing social sets.
- Can only read and write resources that belong to those sets.

Resources outside the restriction are reported as `404`.

A key with no restriction has access to all of the account's social sets.