EYWAL Developers
API 1.0 · 2026-11-17

Đăng nhập bằng EYWAL, mỗi ứng dụng một danh tính riêng.

Sign in with EYWAL. One private identity per app.

EYWAL cho người dùng đăng nhập vào ứng dụng của bạn mà không chia sẻ một mã định danh chung với các ứng dụng khác. Bạn nhận một profileid chỉ có nghĩa trong dự án của bạn, cùng tên và ảnh mà người dùng đồng ý chia sẻ.

EYWAL lets people sign in to your app without sharing one common identifier across apps. You receive a profileid that only means something inside your project, plus the name and picture the user agreed to share.

Your app→/consent→redirect_uri?token&state→POST /session→profileid
Định danh theo ứng dụngApp-scoped identityHai ứng dụng không so được người dùng bằng profileid.Two apps cannot match a user by profileid.
Token một lần, 5 giâyOne-time token, 5 secondsChỉ máy chủ của bạn đổi token lấy hồ sơ.Only your server exchanges it for the profile.
PKCE S256Bật bắt buộc theo dự án; chặn hạ cấp.Enforce per project; blocks downgrade.

Quickstart

Khoảng 5 phút nếu bạn đã có một máy chủ web. Bạn không cần biết EYWAL lưu dữ liệu thế nào bên trong.

About 5 minutes if you already run a web server. You do not need to know how EYWAL stores data internally.

  1. Tạo dự án. Đăng nhập eywal.com/projects → Tạo dự án → thêm một ứng dụng. Chép mã kết nối dạng epc_….
    Create a project. Sign in at eywal.com/projects → Create project → add an app. Copy the connection id (epc_…).
  2. Thêm và xác minh redirect_uri. Ví dụ https://app.example.com/auth/callback. Tải file xác minh, đặt lên domain của bạn, bấm Xác minh. Địa chỉ chưa xác minh sẽ không nhận được token.
    Add and verify a redirect_uri. E.g. https://app.example.com/auth/callback. Download the verification file, host it on your domain, press Verify. Unverified addresses never receive tokens.
  3. Bắt đầu đăng nhập từ máy chủ. Tạo state và code_verifier ngẫu nhiên, lưu trong phiên của bạn, rồi chuyển trình duyệt tới /consent kèm code_challenge.
    Start sign-in from your server. Generate a random state and code_verifier, keep them in your session, redirect the browser to /consent with code_challenge.
  4. Nhận token ở callback. Đối chiếu state. Sai thì dừng.
    Receive the token at your callback. Compare state. Stop if it differs.
  5. Đổi token ở máy chủ. POST https://eywal.com/session với project_id, token, redirect_uri, code_verifier. Dùng profileid làm khoá tài khoản.
    Exchange on your server. POST https://eywal.com/session with project_id, token, redirect_uri, code_verifier. Use profileid as the account key.
  6. Bật “Bắt buộc PKCE” trong trang dự án khi luồng đã chạy. Từ đó mọi yêu cầu thiếu PKCE bị từ chối.
    Turn on “Require PKCE” on the project page once the flow works. Requests without PKCE are then rejected.

Developer Console

Console chính là trang quản lý dự án trên eywal.com/projects, dùng tài khoản EYWAL của bạn. Không có tài khoản developer riêng. Ở đó bạn:

The console is the project manager at eywal.com/projects, using your normal EYWAL account. There is no separate developer account. There you:

Ứng dụng & redirectApps & redirectsThêm, xác minh, ngừng tiếp nhận, xoá.Add, verify, disable, delete.
Bắt buộc PKCERequire PKCEBật hoặc tắt theo dự án.Toggle per project.
Client secretTạo mới (hiện đúng 1 lần), gỡ.Rotate (shown once), remove.
Mã kết nốiConnection idepc_… công khai, an toàn để nhúng.epc_… is public and safe to embed.

Luồng đăng nhập

Sign-in flow

Browser ──GET──▶ https://eywal.com/consent
                   ?project_id=epc_…&redirect_uri=…&state=…
                   &code_challenge=…&code_challenge_method=S256
        (user signs in if needed, picks a profile, consents)
Browser ◀─302── https://app.example.com/auth/callback?token=…&state=…
Your server ─POST─▶ https://eywal.com/session
                   project_id, token, redirect_uri, code_verifier[, client_secret]
Your server ◀─200── { "status":"ok", "profileid":"…", "name":"…", … }
Bắt đầu luồng tại /consent. Nút có sẵn trong sdk.js hiện đi qua /sign-in và chưa gửi state hay PKCE, nên không dùng được với dự án đã bật bắt buộc PKCE.
Start the flow at /consent. The ready-made button in sdk.js currently goes through /sign-in and does not send state or PKCE, so it does not work for projects that require PKCE.

PKCE S256

code_verifier: 43–128 ký tự [A-Za-z0-9._~-], ngẫu nhiên, giữ ở máy chủ của bạn. code_challenge = BASE64URL(SHA256(code_verifier)), không có dấu =. Chỉ nhận S256; plain bị từ chối.

code_verifier: 43–128 random chars from [A-Za-z0-9._~-], kept on your server. code_challenge = BASE64URL(SHA256(code_verifier)) without = padding. Only S256 is accepted; plain is rejected.

Khi dự án bật “Bắt buộc PKCE”, EYWAL kiểm ở hai nơi: màn consent không phát token nếu thiếu code_challenge, và /session trả pkce_required. Tham số URL không tắt được chính sách này.
With “Require PKCE” on, EYWAL checks twice: consent issues no token without code_challenge, and /session returns pkce_required. URL parameters cannot switch the policy off.

Client secret

Chỉ dành cho ứng dụng có máy chủ giữ được bí mật. Ứng dụng di động, desktop hoặc web chỉ có JavaScript không dùng secret; hãy dùng PKCE. Khi dự án đã tạo secret, mọi lần gọi /session phải gửi client_secret. EYWAL chỉ lưu bản băm SHA-256; secret thô hiện một lần lúc tạo.

Only for apps with a server that can keep a secret. Mobile, desktop and JavaScript-only web apps do not use a secret; use PKCE. Once a project has a secret, every /session call must send client_secret. EYWAL stores only its SHA-256 hash; the raw secret is shown once.

Danh tính & quyền riêng tư

Identity & privacy

Hồ sơProfileBạn nhậnYou receive
basicprofileid, tên, ảnh. Không email, không số điện thoại.profileid, name, picture. No email, no phone.
anonymousprofileid khác hẳn hồ sơ chính, tên “Ẩn danh XXXXX”, ảnh mặc định.A profileid unrelated to the main profile, name “Ẩn danh XXXXX”, default picture.
verifiedChỉ khi dự án ở chế độ verified và người dùng đã xác minh: thêm email, số điện thoại.Only for verified-mode projects with a verified user: adds email and phone.

Người dùng xem và thu hồi quyền của ứng dụng trong Bản thể số → Ứng dụng đã kết nối. Thu hồi nghĩa là lần sau ứng dụng phải hỏi lại người dùng; phiên bạn đã tạo vẫn tồn tại tới khi ứng dụng của bạn tự kiểm lại.

Users review and revoke app access in Digital identity → Connected apps. Revoking means your app must ask again next time; sessions you already created remain until your app re-checks.

Đang chuyển mã hồ sơ (F-08). Phản hồi hiện kèm profileid_next. Hãy lưu nó cạnh profileid. Khi EYWAL chuyển sang mã mới, profileid sẽ là mã mới và profileid_legacy là mã cũ để bạn ánh xạ tài khoản.
Profile id migration (F-08). Responses now include profileid_next. Store it next to profileid. When EYWAL switches, profileid becomes the new id and profileid_legacy carries the old one for account mapping.

API Reference

GET /consent trình duyệtbrowser

ParamMô tảDescription
project_idrequiredMã kết nối epc_ + 32 hex.Connection id epc_ + 32 hex.
redirect_urirequiredTrùng một địa chỉ đã xác minh.Must equal a verified address.
staterecommended[A-Za-z0-9._~-]{1,128}, trả lại nguyên văn.[A-Za-z0-9._~-]{1,128}, echoed back unchanged.
code_challengerecommended43 ký tự base64url. Bắt buộc nếu dự án bật PKCE.43 base64url chars. Required if the project requires PKCE.
code_challenge_methodoptionalS256
modeoptionalGợi ý hồ sơ: basic, anonymous, verified.Profile hint: basic, anonymous, verified.

POST /session chỉ máy chủserver only

application/x-www-form-urlencoded. Token chỉ nhận trong thân POST hoặc Authorization: Bearer, không nhận trên URL.

application/x-www-form-urlencoded. The token is accepted only in the POST body or Authorization: Bearer, never in the URL.

FieldMô tảDescription
project_idrequiredepc_…
tokenrequiredToken từ callback, dùng một lần, 5 giây.Token from the callback, single use, 5 seconds.
redirect_urirecommendedNếu gửi, phải trùng nơi token được phát.If sent, must equal where the token was issued.
code_verifierif PKCEBắt buộc khi đã gửi code_challenge.Required when code_challenge was sent.
client_secretif setBắt buộc khi dự án đã tạo secret.Required when the project has a secret.
{
  "status": "ok",
  "project_id": "epc_2343d2c6…",
  "profileid": "200bf9c2…31024",
  "profile_mode": "basic",
  "project_profile_mode": "basic",
  "user_verified": 0,
  "name": "Nguyễn An",
  "avatar": "/data/uploads/avatars/….webp",
  "email": "",
  "phone": "",
  "profileid_next": "9c4e…"
}

Đặc tả OpenAPI đầy đủ: openapi.yaml (đi kèm bản phát hành portal).

Full OpenAPI spec: openapi.yaml (ships with the portal release).

Lỗi

Errors

HTTPerrorNghĩa & cách xử lýMeaning & fix
400pkce_requiredDự án bắt buộc PKCE mà token không có. Gửi code_challenge ở /consent.Project requires PKCE and the token has none. Send code_challenge to /consent.
401invalid_grantcode_verifier thiếu hoặc không khớp. Token đã bị tiêu, bắt đầu lại.code_verifier missing or wrong. The token is spent; start over.
401invalid_clientThiếu hoặc sai client_secret.Missing or wrong client_secret.
401token không hợp lệinvalid tokenSai, đã dùng, hoặc quá 5 giây.Wrong, already used, or older than 5 seconds.
403Invalid project_idMột thông báo chung cho mọi lỗi dự án/địa chỉ (sai id, redirect chưa xác minh hoặc đã tắt, redirect không khớp). EYWAL cố ý không nói rõ lý do.One generic message for every project/address problem (wrong id, unverified or disabled redirect, redirect mismatch). EYWAL deliberately hides the reason.
429—Gọi quá nhanh. Lùi lại rồi thử.Too many requests. Back off and retry.

Ví dụ mã

Code examples

// 1) /login — bắt đầu
session_start();
$b64 = fn($b) => rtrim(strtr(base64_encode($b), '+/', '-_'), '=');
$_SESSION['eywal_state']    = $b64(random_bytes(24));
$_SESSION['eywal_verifier'] = $b64(random_bytes(32));
$q = http_build_query([
  'project_id' => 'epc_YOUR_ID', 'redirect_uri' => 'https://app.example.com/auth/callback',
  'state' => $_SESSION['eywal_state'],
  'code_challenge' => $b64(hash('sha256', $_SESSION['eywal_verifier'], true)), 'code_challenge_method' => 'S256',
]);
header('Location: https://eywal.com/consent?' . $q); exit;

// 2) /auth/callback — đổi token
session_start();
if (!hash_equals($_SESSION['eywal_state'] ?? '', $_GET['state'] ?? '')) exit('state mismatch');
$ch = curl_init('https://eywal.com/session');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10,
  CURLOPT_POSTFIELDS => http_build_query(['project_id' => 'epc_YOUR_ID', 'token' => $_GET['token'] ?? '',
    'redirect_uri' => 'https://app.example.com/auth/callback', 'code_verifier' => $_SESSION['eywal_verifier']])]);
$r = json_decode((string)curl_exec($ch), true);
unset($_SESSION['eywal_state'], $_SESSION['eywal_verifier']);
if (($r['status'] ?? '') !== 'ok') exit('sign-in failed');
$accountKey = $r['profileid'];   // lưu cả $r['profileid_next']

Playground

Tạo state, code_verifier, code_challenge và URL consent ngay trong trình duyệt của bạn. Trang không gửi gì đi đâu và không dùng dữ liệu thật.

Generate state, code_verifier, code_challenge and a consent URL in your browser. Nothing is sent anywhere and no real data is used.

Checklist lên production

Go-live checklist

  • redirect_uri dùng HTTPS và đã xác minh.redirect_uri uses HTTPS and is verified.
  • Luồng bắt đầu ở /consent với state và PKCE S256; callback đối chiếu state bằng so sánh thời gian hằng số.Flow starts at /consent with state and PKCE S256; the callback compares state in constant time.
  • Đã bật “Bắt buộc PKCE” trong trang dự án.“Require PKCE” is on for the project.
  • /session chỉ gọi từ máy chủ, có timeout; token không ghi vào log./session is called from the server only, with a timeout; tokens never go to logs.
  • client_secret (nếu dùng) nằm trong biến môi trường máy chủ, không trong mã nguồn hay app.client_secret (if used) lives in server environment variables, never in source or apps.
  • Khoá tài khoản là profileid; đã lưu thêm profileid_next.Accounts are keyed by profileid; profileid_next is stored too.
  • Không dùng tên hay ảnh để ghép tài khoản.Never match accounts by name or picture.
  • Phiên của bạn có hạn và kiểm lại EYWAL định kỳ để tôn trọng thu hồi.Your sessions expire and re-check EYWAL periodically to honour revocation.

Giới hạn hiện tại

Current limits

  • EYWAL dùng giao thức riêng. Chưa tương thích OpenID Connect: không có /authorize, /token, id_token hay trang discovery.
  • EYWAL uses its own protocol. It is not OpenID Connect compatible yet: no /authorize, /token, id_token or discovery document.
  • sdk.js chưa hỗ trợ state/PKCE (xem Luồng đăng nhập).
  • sdk.js does not support state/PKCE yet (see Sign-in flow).
  • Chưa có refresh token; mỗi lần đăng nhập là một lần đổi token.
  • No refresh tokens; each sign-in is one exchange.
  • Chưa có môi trường sandbox công khai; Playground chỉ tạo giá trị cục bộ.
  • No public sandbox environment yet; the Playground only generates values locally.

Changelog

2026-11-17PKCE S256, client secret, “Bắt buộc PKCE” theo dự án; người dùng thu hồi được quyền ứng dụng.PKCE S256, client secret, per-project “Require PKCE”; users can revoke app access.
2026-11-16state trả lại nguyên văn; /session kiểm redirect_uri nếu được gửi.state echoed back; /session checks redirect_uri when sent.
2026-11-15Mã kết nối công khai epc_…; bắt đầu chuyển mã hồ sơ (profileid_next).Public connection id epc_…; profile id migration starts (profileid_next).
Bản xem trước. Tài liệu viết theo mã đang chạy ngày 2026-11-17. Trang này độc lập với hệ thống lõi EYWAL: không có cơ sở dữ liệu, không giữ bí mật.