@pelican-identity/vanilla 1.0.42 → 1.0.44

package/README.md

@@ -215,6 +215,95 @@ interface IdentityResult {
 }
 ```
 
+## `token`
+
+- A **JWT (JSON Web Token)** issued by Pelican after a successful user authentication or action approval.
+- This token represents a **verified user interaction** and can be used to confirm identity and/or intent on your backend.
+
+---
+
+## Verification
+
+To verify a Pelican token, your backend must send it to the Pelican Identity API.
+
+### Endpoint
+
+```
+POST https://identityapi.pelicanidentity.com/verify-session
+```
+
+---
+
+### Headers
+
+Include the following headers in your request:
+
+- `x-public-key` — Your Pelican public API key
+
+---
+
+### Request Body
+
+```json
+{
+  "token": "YOUR_PELICAN_JWT_TOKEN"
+}
+```
+
+---
+
+### Example (Node.js)
+
+```ts
+const response = await fetch(
+  "https://identityapi.pelicanidentity.com/verify-session",
+  {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "x-public-key": process.env.PELICAN_PUBLIC_KEY,
+    },
+    body: JSON.stringify({
+      token: pelicanToken,
+    }),
+  },
+);
+
+const data = await response.json();
+```
+
+---
+
+### Response
+
+A successful response will return a verified payload containing:
+
+- `pelican_id ` — Pelican user identity details
+- `verified` — Boolean indicating token validity
+- `issued_at` — Timestamp of when the token was generated
+- `expires_at` — Token expiration timestamp
+
+---
+
+### Example Response
+
+```json
+{
+  "verified": true,
+  "pelican_id": "4dbde492db8f64aff80b1dd61754a84bdf2dc87eed1b19fec4cd66569856b134",
+  "issued_at": 1714483200,
+  "expires_at": 1714483500
+}
+```
+
+---
+
+### Notes
+
+- Always verify the token on your backend before trusting any user action.
+- Tokens are **short-lived** and should not be reused.
+- Never trust tokens directly from the client without verification.
+
 ---
 
 ## `user_id`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pelican-identity/vanilla",
-  "version": "1.0.42",
+  "version": "1.0.44",
   "description": "JavaScript components for Pelican Identity authentication",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -19,7 +19,7 @@
     "package.json"
   ],
   "dependencies": {
-    "@pelican-identity/auth-core": "^1.2.45"
+    "@pelican-identity/auth-core": "^1.2.47"
   },
   "devDependencies": {
     "tsup": "^8.0.1",