Masuk
Mini App bisa memasukkan orang yang sedang memakai Cowork dengan akun Micromeet-nya, lalu memanggil Micromeet atas nama orang itu dari backend-nya sendiri. Halaman tidak pernah melihat kata sandi, token, atau secret Mini App: Cowork hanya memberi halaman sebuah code sekali pakai, dan backend Mini App menukarnya dengan token.
Hanya Mini App terpasang yang paketnya sudah ditandatangani Micromeet, dengan sedikitnya satu domain server yang sudah diverifikasi, yang bisa memasukkan pengguna (lihat Pengemasan dan Tanda Tangan). Mini App bawaan tidak punya modul ini.
MAESTROSDK.auth.login(params?) Belum dirilis
Meminta code sekali pakai kepada Cowork, untuk Mini App ini dan orang yang sedang masuk ke Cowork.
Parameter
| Field | Tipe | Wajib | Deskripsi |
|---|---|---|---|
scopes | string[] | Tidak | Izin yang diminta Mini App, misalnya ['profile:read']. Jika tidak diisi, berarti semua izin yang dibolehkan Micromeet untuk Mini App ini |
Pada panggilan pertama, Cowork menampilkan kartu kepada pengguna: nama dan pengembang Mini App, izin yang diminta, dan akun yang akan dipakai; tombolnya Izinkan dan Batal, dengan Batal sebagai pilihan bawaan. Kartu hanya muncul di tab yang sedang dilihat pengguna. Setelah diizinkan sekali, panggilan berikutnya untuk izin yang sama langsung mendapat code tanpa kartu.
Nilai kembalian
Promise<{ ok: true; code: string; region: 'SG' | 'HK' | 'ID'; expiresIn: number } | { ok: false; error: string }>
Code hanya bisa dipakai sekali dan berlaku 5 menit (expiresIn dalam detik). Kirim code dan region ke backend Anda.
error | Artinya |
|---|---|
unsigned | Paket tidak ditandatangani Micromeet, atau halaman bukan Mini App yang terpasang |
tampered | Ada file Mini App yang berubah setelah dipasang; Cowork sudah menutupnya |
host_signed_out | Tidak ada yang masuk ke Cowork, atau halaman dibuka untuk akun lain. Jika ini tab yang sedang dilihat pengguna, Cowork membuka halaman masuknya |
user_cancelled | Pengguna membatalkan, tab ada di latar belakang, atau akun berganti saat kartu terbuka |
app_not_available | AppID ini tidak terdaftar di region ini, atau dinonaktifkan |
version_not_available | Versi ini tidak terdaftar atau sudah dinonaktifkan: perbarui Mini App |
no_server_domain | Versi ini tidak punya domain server yang sudah diverifikasi, atau salah satu domainnya tidak lagi terverifikasi (lihat Pengemasan dan Tanda Tangan) |
scope_denied | Meminta izin yang tidak dibolehkan Micromeet untuk Mini App ini, atau scopes bukan daftar string |
rate_limited | Terlalu banyak code dalam satu menit; coba lagi sebentar lagi |
network | Cowork tidak bisa menghubungi Micromeet |
MAESTROSDK.auth.status() Belum dirilis
Promise<{ signed: boolean; host: 'cowork'; hostSignedIn: boolean }>. signed bernilai true jika tanda tangan paket valid dan tidak ada file yang berubah; hostSignedIn bernilai true jika ada yang masuk ke Cowork. Gunakan untuk menentukan apakah tombol masuk perlu ditampilkan.
Di backend Mini App
Backend menyimpan client secret yang diberikan Micromeet saat mendaftarkan AppID, satu untuk setiap region tempat Mini App didaftarkan; jangan pernah menaruhnya di halaman atau paket. Backend berjalan di salah satu domain server Mini App yang sudah diverifikasi (lihat Pengemasan dan Tanda Tangan). Contoh langkah demi langkah ada di Membuat Mini App dengan Masuk.
Request dari halaman
Origin halaman adalah miniapp://<appId>. Jawab request-nya dengan Access-Control-Allow-Origin: miniapp://<appId>, dan preflight-nya (OPTIONS) dengan method dan header yang dikirimnya; jika tidak, request gagal di halaman sebelum sampai ke kode Anda. Simpan token Micromeet di backend dan beri halaman sesi milik Anda sendiri.
Helper
@micromeet-ai/miniapp-sdk/server bisa dipakai dari ESM maupun CommonJS di Node.js 18 atau lebih baru.
import { createMiniappAuthClient, MiniappAuthError } from '@micromeet-ai/miniapp-sdk/server';
const auth = createMiniappAuthClient({ appId: 'ai.example.app', clientSecret: process.env.MINIAPP_SECRET_HK });
const tokens = await auth.exchangeCode({ code, region });
const me = await auth.profile({ accessToken: tokens.accessToken, region: tokens.region });| Opsi | Wajib | Keterangan |
|---|---|---|
appId | Ya | AppID |
clientSecret | Ya | Secret region yang dipanggil client ini; buat satu client per region |
coreUrl | Tidak | (region) => alamat: Micromeet mana yang dipanggil. Default: produksi, per region |
fetch | Tidak | Mengganti fetch global |
timeoutMs | Tidak | Per request; default 15000 |
| Fungsi | Hasil |
|---|---|
exchangeCode({ code, region }) | Token: accessToken, expiresIn (detik), refreshToken, scope (daftar), user: { ref, name, email }, institution: { iid, name }, region |
refresh({ refreshToken, region }) | Set token baru; refresh token lama tidak berlaku lagi, simpan yang baru |
revoke({ refreshToken, region }) | Tidak ada; mengeluarkan orang itu dari Mini App |
profile({ accessToken, region }) | { ref, name, email, institution: { iid, name }, region } (profile:read) |
call({ accessToken, region, path, body? }) | data dari POST ke route Micromeet yang menerima token Mini App |
Jika gagal, setiap fungsi melempar MiniappAuthError dengan code dari Micromeet dan status HTTP (lihat Galat di bawah).
Token
| Token | Masa berlaku | Kegunaan |
|---|---|---|
| Access token | 15 menit | Authorization: Bearer pada route yang menerima token Mini App |
| Refresh token | 30 hari | refresh memberi pasangan baru; setiap refresh token hanya berlaku sekali |
- Gunakan region yang datang bersama code untuk semua panggilan berikutnya; token hanya berlaku di region-nya.
- Token berlaku untuk orang itu dan untuk institusi yang dipilihnya di Cowork saat masuk.
user.refadalah id tetap orang ini di Mini App ini (Mini App lain mendapat id lain): pakai sebagai kunci pengguna Anda.- Kata sandi yang diubah, keluar dari semua perangkat, keluar dari institusi, versi yang dinonaktifkan, atau Mini App yang dinonaktifkan menghentikan token pada request berikutnya.
Scope dan route
| Scope | Route | Hasil |
|---|---|---|
profile:read | POST /share/miniapp/profile | { ref, name, email, institution: { iid, name }, region } |
Token hanya berlaku pada route di tabel ini, untuk scope yang diizinkan orang itu, dan tidak pernah melebihi apa yang boleh dilakukan orang itu di Micromeet.
Galat
code | HTTP | Yang terjadi |
|---|---|---|
invalid_client | 401 | AppID atau secret salah untuk region ini, atau secret sudah diganti |
invalid_grant | 400 | Code sudah dipakai, lebih dari 5 menit, atau untuk AppID lain; refresh token sudah dipakai, dicabut, atau lebih dari 30 hari; atau orang itu mengganti kata sandi, keluar dari semua perangkat, atau keluar dari institusi: masuk lagi |
app_not_available | 400 | Mini App dinonaktifkan di region ini |
version_not_available | 400 | Versi yang dipakai orang itu saat masuk sudah dinonaktifkan: perbarui Mini App |
needLogin | 401 | Pada route: access token kedaluwarsa atau tidak berlaku lagi. Panggil refresh; jika gagal, masuk lagi |
forbidden | 403 | Pada route: token tidak memegang scope route itu, atau orang itu tidak boleh melakukan ini di Micromeet |
network | — | Helper tidak bisa menghubungi Micromeet (status 0) |
params_invalid | 400, atau — | grant_type salah; atau, di helper, region tidak dikenal atau path yang bukan route (status 0, tidak ada request terkirim) |
Panggilan HTTP
Backend dalam bahasa lain melakukan panggilan yang sama. Masing-masing adalah POST dengan body JSON ke Micromeet di region code itu:
| Region | Alamat |
|---|---|
| SG | https://crms-api.micromeet.ai |
| HK | https://crms-api-hk.micromeet.ai |
| ID | https://crms-api-id.micromeet.ai |
| Path | Body | data di jawaban |
|---|---|---|
/miniapp-open/auth/token | { "grant_type": "authorization_code", "app_id", "client_secret", "code" } | { access_token, token_type: "Bearer", expires_in, refresh_token, scope, user: { ref, name, email }, institution: { iid, name }, region }; scope dipisahkan spasi |
/miniapp-open/auth/token | { "grant_type": "refresh_token", "app_id", "client_secret", "refresh_token" } | Sama |
/miniapp-open/auth/revoke | { "app_id", "client_secret", "refresh_token" } | { revoked: true } |
/share/miniapp/profile | {}, dengan Authorization: Bearer <access_token> | { ref, name, email, institution: { iid, name }, region } |
Berhasil dijawab dengan { "code": 0, "success": true, "data": … }. Gagal dijawab dengan { "code": "<galat>", "msg": "…", "success": false } dengan status HTTP seperti di Galat di atas.
Terkait
- Pengemasan dan Tanda Tangan Kemas Mini App dan minta Micromeet menandatanganinya
- Ikhtisar Semua modul Mini App SDK