# Authentication

> Authenticate API requests with a workspace API key or an OAuth access token, and limit what each credential can do.

Every request to `https://api.socialit.com/v1` carries a bearer token in the `Authorization` header. The token is either a **workspace API key** or an **OAuth access token**.

```bash
curl https://api.socialit.com/v1/accounts \
  -H "Authorization: Bearer sk_live_…"
```

## API keys

API keys belong to a workspace. Create them in **Manage → API keys** (workspace admins only).

- Keys start with `sk_live_`. The full key is shown **once**, at creation. Socialit stores only a hash and a short display prefix.
- **Permission:** `full` (read and write) or `read` (read only).
- **Profiles:** optionally restrict a key to some profiles. The key then sees and acts on those profiles' accounts only, which is the safest way to give a key to one client or one integration.
- **Expiry and rotation:** set an expiry date, regenerate a key, or delete it at any time.

Treat keys like passwords: never commit them, never use them in browser code, and rotate them when someone leaves.

## OAuth 2.1

Apps and AI agents that act for *other* Socialit users use OAuth 2.1 with PKCE. Users approve the app on a consent screen and choose which workspaces it can reach. Scopes:

| Scope | Allows |
|---|---|
| `read` | Read posts, accounts, inbox, analytics |
| `write` | Create and change posts, reply in the inbox, upload media |
| `admin` | Workspace administration: members, API keys, webhooks |
| `offline_access` | A refresh token to keep access without the user present |

Socialit supports dynamic client registration, so MCP clients such as Claude and Cursor register themselves; see [MCP server](/docs/mcp/). Users can review and revoke connected apps in **Account → Connected apps**.

## Verify a credential

`GET /v1/auth/verify` returns the workspace, permission and type of the credential you sent, which is useful to check a key at startup:

```json
{ "object": "credential", "workspace": { "id": "ws_…", "name": "Northwind" }, "permission": "full", "type": "api_key", "scopes": [] }
```

## Errors

Missing, invalid, expired or revoked credentials return `401` with `authentication_error`. A valid credential without the right permission (a read-only key creating a post, a member without access to a profile) returns `403` with `permission_error`. See [Errors](/docs/api-reference/errors/).

---

Source: https://socialit.com/docs/authentication/
