Authentication

Pixelfed uses OAuth 2.0 with the authorization code flow. Your app never sees a password, and people can revoke access from their settings at any time.

Register your app on the server to get a client ID and secret.
Send the person to /oauth/authorize on their server. After they approve, they are redirected back to you with a code.
Exchange the code for an access token, then send it as Authorization: Bearer <token> on every request.

Client credentials belong to one server. Register your app again for each new domain and store the credentials keyed by that domain.

Scopes

Ask only for what you need. The approval screen lists every scope you request. If you leave scope out, you get read write follow push.

Scope	Allows
`read`	Read the account, timelines, posts and notifications.
`write`	Publish, edit and delete posts, upload media, like and comment.
`follow`	Follow, unfollow, block and mute accounts.
`push`	Receive push notifications.
`security:read`	See which apps and devices have access to the account. Not granted by default, request it explicitly.
`security:write`	Change the password, revoke other apps and delete the account. Not granted by default.
`admin:read` `admin:write`	Moderation and server settings. Only granted to admin accounts.

Authorization URL

https://pixelfed.social/oauth/authorize
  ?client_id=1842
  &redirect_uri=tintype://oauth-callback
  &response_type=code
  &scope=read+write+follow

Redirect back to your app

tintype://oauth-callback
  ?code=def50200a91c4e7f3b

POST/api/v1/apps

Register an app

Mastodon compatible No token

Body parameters

client_namestringrequired

redirect_urisstringrequired

scopesstring

websitestring

Returns

curl -X POST "https://pixelfed.social/api/v1/apps" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Tintype",
    "redirect_uris": "tintype://oauth-callback",
    "scopes": "read write follow",
    "website": "https://tintype.example"
  }'

const res = await fetch("https://pixelfed.social/api/v1/apps", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    client_name: "Tintype",
    redirect_uris: "tintype://oauth-callback",
    scopes: "read write follow",
    website: "https://tintype.example",
  }),
});

const app = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/api/v1/apps",
    headers={"Accept": "application/json"},
    json={
        "client_name": "Tintype",
        "redirect_uris": "tintype://oauth-callback",
        "scopes": "read write follow",
        "website": "https://tintype.example",
    },
)

app = res.json()

use Illuminate\Support\Facades\Http;

$app = Http::acceptJson()->post('https://pixelfed.social/api/v1/apps', [
    'client_name' => 'Tintype',
    'redirect_uris' => 'tintype://oauth-callback',
    'scopes' => 'read write follow',
    'website' => 'https://tintype.example',
])->json();

Response

{
  "id": "1842",
  "name": "Tintype",
  "website": null,
  "redirect_uri": "tintype://oauth-callback",
  "client_id": "1842",
  "client_secret": "kR2mV9xQpL4tYc7HsW1nB8dJfZ3gA6uE0oNqTiXb",
  "vapid_key": null
}

{
  "message": "The client name field is required.",
  "errors": {
    "client_name": ["The client name field is required."]
  }
}

POST/oauth/token

Get a token

No token

Body parameters

grant_typestringrequired

codestringrequired

client_idstringrequired

client_secretstringrequired

redirect_uristringrequired

Returns

curl -X POST "https://pixelfed.social/oauth/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "def50200a91c4e7f3b",
    "client_id": "1842",
    "client_secret": "kR2mV9xQpL4tYc7HsW1nB8dJfZ3gA6uE0oNqTiXb",
    "redirect_uri": "tintype://oauth-callback"
  }'

const res = await fetch("https://pixelfed.social/oauth/token", {
  method: "POST",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    grant_type: "authorization_code",
    code: "def50200a91c4e7f3b",
    client_id: "1842",
    client_secret: "kR2mV9xQpL4tYc7HsW1nB8dJfZ3gA6uE0oNqTiXb",
    redirect_uri: "tintype://oauth-callback",
  }),
});

const token = await res.json();

import requests

res = requests.post(
    "https://pixelfed.social/oauth/token",
    headers={"Accept": "application/json"},
    json={
        "grant_type": "authorization_code",
        "code": "def50200a91c4e7f3b",
        "client_id": "1842",
        "client_secret": "kR2mV9xQpL4tYc7HsW1nB8dJfZ3gA6uE0oNqTiXb",
        "redirect_uri": "tintype://oauth-callback",
    },
)

token = res.json()

use Illuminate\Support\Facades\Http;

$token = Http::acceptJson()->post('https://pixelfed.social/oauth/token', [
    'grant_type' => 'authorization_code',
    'code' => 'def50200a91c4e7f3b',
    'client_id' => '1842',
    'client_secret' => 'kR2mV9xQpL4tYc7HsW1nB8dJfZ3gA6uE0oNqTiXb',
    'redirect_uri' => 'tintype://oauth-callback',
])->json();

Response

{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOi...",
  "refresh_token": "def50200c3a87be21f..."
}

{
  "error": "invalid_grant",
  "error_description": "The authorization code is invalid or has expired."
}

Pixelfed is free and open source software. Edit this page Report a docs issue