# How to authenticate with the DunSocial API

> Send Authorization: Bearer with either a session token or a personal access token (dun_pat_…), plus X-Workspace-Id on workspace routes. Use a PAT for CI & scripts. A PAT is bound to one workspace, & a mismatch returns 403.

Updated: 2026-10-05.

## The base URL & the header

The DunSocial API is a JSON REST API at `https://api.dunsocial.com`. Almost every request sends a bearer token:

```
Authorization: Bearer <token>
```

Most content routes also need to know which workspace you mean, so they take a second header, covered below.

## Option 1: a session token

A session token comes from signing in with email & password, & it's what apps use on behalf of a person:

```bash
curl -X POST https://api.dunsocial.com/api/auth/sign-in/email \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}'
```

Use the returned token on later requests. Sessions last about 30 days, & new accounts must verify their email first.

## Option 2: a personal access token

For CI, scripts & agents, use a personal access token (PAT). Create one in the app under Settings → CLI, or through the API while signed in:

```bash
curl -X POST https://api.dunsocial.com/api/cli/tokens \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-actions",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "scopes": ["posts:schedule", "posts:publish", "drafts:write"],
    "expiresInDays": 90
  }'
```

The raw token is returned once, in the form `dun_pat_<prefix>_<secret>`. Store it like a password.

## The workspace header

Send the workspace on workspace-scoped routes:

```bash
curl https://api.dunsocial.com/api/posts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID"
```

You must be an active member of that workspace, or the API returns 403. A PAT is bound to a single workspace, so sending a different one is also a 403.

DunSocial uses the header so one token or session can work across several workspaces without ambiguity.

## What a PAT can't do

PATs deliberately can't call AI routes, manage webhook endpoints, read notifications, touch billing or manage other tokens. Those need a session.

That limit is a feature. DunSocial keeps the powerful account-level actions behind a person's sign-in, so a leaked CI token can post but can't reconfigure the workspace.

## Listing & revoking tokens

`GET /api/cli/tokens` lists token metadata with no secrets, & `DELETE /api/cli/tokens/:id` revokes one. Set an expiry when you create a token, & revoke it as soon as a job no longer needs it.

DunSocial's CLI & SDK use exactly the same tokens & headers, so a PAT created once works across the CLI, the SDK & raw HTTP.

## Which one to use

Use a session token when a person is signing in to your own app. Use a PAT for everything unattended. For AI assistants in chat hosts, use MCP, which authenticates with OAuth & needs no token at all.

DunSocial's three surfaces differ only in how they authenticate, so pick by who is calling, not by what you want to do.

## Related guides

- [Which PAT scopes should you grant for each automation job?](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/which-pat-scopes-should-you-grant-for-each-automation-job.md)
- [What is a personal access token & how does it secure API access?](https://www.dunsocial.com/hub/social-media-automation-for-developers/what-is-a-personal-access-token-and-how-does-it-secure-api-access.md)
- [What can you automate with a social media API?](https://www.dunsocial.com/hub/social-media-automation-for-developers/what-can-you-automate-with-a-social-media-api.md)
- [How to schedule a post with the DunSocial API](https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-schedule-a-post-with-the-dunsocial-api.md)

## About this document

This is the Markdown representation of https://www.dunsocial.com/hub/dunsocial-api-and-sdk-guides/how-to-authenticate-with-the-dunsocial-api. The HTML version of the same page is at the same URL. You can also request Markdown from any page by sending `Accept: text/markdown`.

Machine-readable summary of the whole site: https://www.dunsocial.com/llms.txt

## Company

- Product: DunSocial, https://www.dunsocial.com
- Legal entity: THISUX PRIVATE LIMITED, Chennai, Tamil Nadu, India
- Support: support@dunsocial.com
- Open the app: https://app.dunsocial.com/login