Autentikasi

Setiap panggilan membawa token Bearer di header Authorization. Sofia membaca hak akses di baliknya pada setiap panggilan: orang yang dikeluarkan dari Workspace, atau otorisasi yang dicabut, menghentikan token pada permintaan berikutnya.

Kunci pribadi

Buat kunci di Pengaturan › API › Akses pribadi. Kunci bertindak atas nama Anda di semua Workspace Anda: usaha yang Anda sebut menentukan Workspace, dan peran Anda di sana menentukan apa yang boleh dilakukan kunci.

curl https://api.sofia-post.com/api/v1/establishments \
  -H "Authorization: Bearer sofia_pk_live_…"

OAuth: authorization code dengan PKCE

Daftarkan klien di Pengaturan › API › Klien aplikasi: nama, logo, kebijakan privasi, izin yang boleh diminta, dan URL pengalihan https. Klien confidential punya secret; klien public (aplikasi seluler, ekstensi browser) tidak punya dan hanya mengandalkan PKCE.

Arahkan orang tersebut ke endpoint otorisasi dengan PKCE challenge (S256 wajib) dan state yang Anda simpan di sesinya:

import { createHash, randomBytes } from 'node:crypto';

const verifier = randomBytes(32).toString('base64url');
const challenge = createHash('sha256').update(verifier).digest('base64url');
const state = randomBytes(16).toString('base64url');

const url = new URL('https://api.sofia-post.com/api/v1/oauth/authorize');
url.search = new URLSearchParams({
  response_type: 'code',
  client_id: process.env.SOFIA_CLIENT_ID,
  redirect_uri: 'https://app.example.com/oauth/callback',
  scope: 'establishments:read posts:read posts:write offline_access',
  state,
  code_challenge: challenge,
  code_challenge_method: 'S256',
}).toString();

Orang tersebut masuk ke Sofia, melihat nama, logo, dan izin Anda, memilih Workspace, lalu menyetujui. Sofia kemudian mengembalikannya ke URL pengalihan Anda dengan code, state Anda, dan penerbit iss. Periksa keduanya, lalu tukarkan kodenya:

curl -X POST https://api.sofia-post.com/api/v1/oauth/token \
  -u "$SOFIA_CLIENT_ID:$SOFIA_CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code=$CODE \
  -d redirect_uri=https://app.example.com/oauth/callback \
  -d code_verifier=$VERIFIER

{
  "access_token": "sofia_live_at_…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "establishments:read posts:read posts:write offline_access",
  "refresh_token": "sofia_live_rt_…"
}

• Kode berlaku 5 menit dan hanya sekali. Jika dipakai ulang, kode ditolak dan token yang dihasilkannya berhenti berfungsi.
• Access token berlaku satu jam dan hanya bertindak pada Workspace yang dipilih orang tersebut.
• refresh_token hanya dikembalikan bila Anda meminta offline_access. Sekali pakai: simpan yang baru setiap kali. Memakai ulang refresh token yang sudah terpakai mencabut seluruh otorisasi.

curl -X POST https://api.sofia-post.com/api/v1/oauth/token \
  -u "$SOFIA_CLIENT_ID:$SOFIA_CLIENT_SECRET" \
  -d grant_type=refresh_token \
  -d refresh_token=$REFRESH_TOKEN

OAuth: client credentials

Klien confidential juga dapat bertindak pada Workspace milik pemiliknya, tanpa orang di tengah prosesnya. Bila klien memegang beberapa Workspace, sebutkan satu dengan workspace_id.

curl -X POST https://api.sofia-post.com/api/v1/oauth/token \
  -u "$SOFIA_CLIENT_ID:$SOFIA_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d workspace_id=$WORKSPACE_ID

Izin (scope)

Panggilan tanpa scope yang dibutuhkan dijawab 403 insufficient_scope. Metadata server (RFC 8414) mencantumkan setiap endpoint dan scope:

https://api.sofia-post.com/.well-known/oauth-authorization-server/api/v1/oauth