OAuth2

Autentikasi OAuth2

Biarkan akun Sofia lain menghubungkan aplikasi Anda: daftarkan client, jalankan alur authorization code dengan PKCE, perbarui token, dan minta scope yang tepat.

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:

javascript

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:

bash

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

json

{
  "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.

bash

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.

bash

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)

Scope	Mengizinkan
`establishments:read`	Menampilkan daftar usaha
`accounts:read`, `accounts:write`	Membaca jaringan yang terhubung; membuat tautan koneksi
`media:read`, `media:write`	Membaca pustaka media; mengunggah dan mengimpor media
`posts:read`, `posts:write`	Menampilkan dan memantau postingan; memublikasikan, mengedit, dan menghapusnya
`insights:read`	Membaca statistik
`webhooks:read`, `webhooks:write`	Menampilkan webhook; mendaftarkan, menguji, dan menghapusnya
`offline_access`	Hanya OAuth: menerima refresh token

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

text

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