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

# Authentication

> Authenticate all API requests using your API key.

## API Key Authentication

All Snipp API endpoints require authentication. Include your API key in the `api-key` header with every request.

```
api-key: YOUR_API_KEY
```

### Where to Find Your API Key

API keys belong to **apps**. Each app is a named key, such as one for ShareX and one for a script, so you can revoke one without breaking the others. You can create up to 10 apps, and every app uploads to your own gallery and counts against your own quota.

1. Sign in to your account.
2. Go to **Settings** and open **Apps**.
3. Create an app, or open an existing one, and copy its API key.

### Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.snipp.gg/users/@me" \
    -H "api-key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch("https://api.snipp.gg/users/@me", {
    headers: { "api-key": "YOUR_API_KEY" },
  });
  const data = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://api.snipp.gg/users/@me",
      headers={"api-key": "YOUR_API_KEY"},
  )
  data = res.json()
  ```
</CodeGroup>

### API Key Permissions

Every key can upload. Reaching the uploads already in your gallery is a separate permission, set per app and off by default:

| Permission | Description |
| - | - |
| **Base** | Upload files, convert files, fetch users and posts, report. Always enabled. |
| **Gallery** | List, edit, add files to, and delete posts you already have. Off by default. Turn it on with the **Gallery Access** switch on the app's page under **Apps** in settings. |

Without gallery access, `GET /posts`, `PATCH /posts/{code}`, `DELETE /posts/{code}`, `POST /posts/{code}/files` and `DELETE /posts/{code}/files/{name}` return `403` with type `forbidden`. `POST /upload` is unaffected.

You can check whether gallery access is enabled by calling `GET /users/@me` and reviewing the `key_has_uploads_access` field, which reports the key used for that request. The field name is historical and reports gallery access.

### Team Access Keys

[Teams](/concepts/plans#teams) (an Ultra feature) each have a dedicated **access key**. A team key is passed in the same `api-key` header as a personal API key, and uploads made with it go to the team's shared gallery instead of a personal account. It is only accepted on `POST /upload`, `PATCH /posts/{code}`, `DELETE /posts/{code}`, `POST /posts/{code}/files`, `DELETE /posts/{code}/files/{name}` and `POST /convert`. Every other endpoint, including `GET /users/@me`, `GET /posts` and `GET /posts/{code}`, returns `401` for a team key. Read team posts with a member's personal key.

```
api-key: YOUR_TEAM_ACCESS_KEY
```

Key differences when uploading with a team key:

* Files are stored in the **team gallery**, not a personal gallery.
* Uploads count against the **team's** weekly quota, never a member's personal quota.
* Team-key uploads are always created **private**, regardless of the `post-privacy` header, and their privacy cannot be changed afterward. Team posts are never **unlisted** or **public**.
* Only the team owner can regenerate or delete the key, from the team's settings page.
* If the team's subscription lapses, `POST /upload`, `POST /posts/{code}/files` and `POST /convert` with the key return `403` with type `forbidden`. Editing and deleting existing team posts keep working.
* If the team owner's account is suspended, the key is refused on every endpoint with the same `403` a suspended personal key gets, with type `suspended`.

The same key also works on the [Relay API](/relay-reference/introduction), passed in its `relay-key` header, on the same endpoints.

Anyone who holds a team key can upload with it, so treat it like any other credential and share it only with trusted team members.

### Security Best Practices

* **Never expose your API key** in client-side code, public repositories, or shared documents.
* **Use environment variables** in production (for example, `process.env.SNIPP_API_KEY`).
* **Use one app per integration** so a leaked key can be revoked without touching anything else.
* **Rotate your key** immediately if you suspect it has been compromised. You can regenerate it, or delete the app, under **Apps** in settings.
* **Limit upload access** if your integration only needs read access.

### Error Responses

| Status | Type | Cause |
| - | - | - |
| `401` | `unauthorized` | Missing `api-key` header |
| `401` | `unauthorized` | Invalid key, or a team key on an endpoint that does not accept one |
| `403` | `suspended` | Your account, or the team owner's, is suspended |
| `403` | `forbidden` | The key has no gallery access, or the team's subscription has lapsed |

Every error returns an `error` object with `type` and `message`. See [Errors](/concepts/errors).


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