From a06b89d0c01f6282ea20dda91c5e8ca22233e6b8 Mon Sep 17 00:00:00 2001 From: Smaranjit Maiti <26691214+smaranjit@users.noreply.github.com> Date: Wed, 7 Oct 2026 03:01:36 +0530 Subject: [PATCH] Make the project easier to find from search --- Cargo.toml | 2 +- README.md | 2 + docs/book.toml | 2 +- docs/src/SUMMARY.md | 1 + docs/src/faq.md | 88 ++++++++++++++++++++++++++++++++++++++++ docs/src/introduction.md | 5 ++- 6 files changed, 97 insertions(+), 3 deletions(-) create mode 100644 docs/src/faq.md diff --git a/Cargo.toml b/Cargo.toml index fffa424..58adc0a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,7 +14,7 @@ license = "MIT" readme = "README.md" repository = "https://github.com/smaranjit/firebase-token-toolkit" homepage = "https://github.com/smaranjit/firebase-token-toolkit" -keywords = ["firebase", "auth", "jwt", "gui", "egui"] +keywords = ["firebase", "firebase-auth", "id-token", "jwt", "app-check"] categories = ["development-tools", "gui", "authentication"] # NOT excluding /assets: main.rs include_bytes!s icon-256.png and build.rs reads # icon.ico, so dropping it here would break a packaged build. diff --git a/README.md b/README.md index 96a8432..481248f 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ A native desktop GUI for the Firebase auth tokens you need during development and testing — mint custom tokens from a UID, exchange them for ID tokens, edit a user's custom claims, and pull App Check debug tokens. One window, no Node, no webview, no Java runtime. +Use it to test any API that expects a Firebase ID token — paste it into Postman, curl or your own tests, and it passes `verifyIdToken` like a token from a signed-in user. It works with web, Android and iOS apps, including API keys restricted to one app. Common questions are answered in the [FAQ](https://smaranjit.github.io/firebase-token-toolkit/faq.html). + [![CI](https://github.com/smaranjit/firebase-token-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/smaranjit/firebase-token-toolkit/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) [![Docs](https://img.shields.io/badge/docs-user%20guide-blue.svg)](https://smaranjit.github.io/firebase-token-toolkit/) diff --git a/docs/book.toml b/docs/book.toml index 259db7f..670c776 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -1,6 +1,6 @@ [book] title = "Firebase Token Toolkit" -description = "User guide for Firebase Token Toolkit, a desktop app for minting and inspecting Firebase auth tokens." +description = "Generate Firebase ID tokens and custom tokens for API testing, edit custom claims, and get App Check debug tokens: the guide to Firebase Token Toolkit, a free desktop app for web, Android and iOS projects." authors = ["Smaranjit Maiti"] language = "en" src = "src" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index d2dfd7b..27da1ec 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -25,5 +25,6 @@ - [Settings and storage](reference/settings-storage.md) - [Google endpoints](reference/endpoints.md) - [Troubleshooting](troubleshooting.md) +- [FAQ](faq.md) - [Security](security.md) - [Building and contributing](contributing.md) diff --git a/docs/src/faq.md b/docs/src/faq.md new file mode 100644 index 0000000..7b26357 --- /dev/null +++ b/docs/src/faq.md @@ -0,0 +1,88 @@ +# FAQ + +Short answers to the questions that usually bring people here, with links to +the full pages. + +## How do I get a Firebase ID token to test my API in Postman or curl? + +Load your service-account key, click **Load apps**, pick a user in the Users +panel, and click **Generate** on the [UID -> ID Token](guide/uid-to-id-token.md) +tab. Click **Copy** and send the token as a bearer token: + +```bash +curl -H "Authorization: Bearer " https://localhost:8080/api/me +``` + +In Postman, choose **Authorization** → **Bearer Token** and paste it. The +[Quick start](quick-start.md) walks through it with screenshots. + +## How do I test a backend that verifies Firebase ID tokens? + +The tokens the app produces are real ID tokens issued by Google for your +project, so they pass `verifyIdToken` in the Firebase Admin SDKs and any other +check against Google's public keys. Generate one for the user you want to test +as, and call your API with it. Add claims for a single token in the **Custom +claims** box to test role checks without touching the user record. + +## How do I sign in as a specific user without their password? + +The app signs a custom token for the user's UID with your service-account key +and exchanges it with Google, the same flow as `createCustomToken` followed by +`signInWithCustomToken`. You never need the user's password, which is also why +the service-account key must be kept safe. See [Security](security.md). + +## How do I set Firebase custom claims without writing code? + +Use the [User Custom Claims](guide/custom-claims.md) tab. **Load current** +shows the user's claims as JSON, you edit them, and **Save** writes them to the +user record, the same as `setCustomUserClaims` in the Admin SDK. A counter keeps +you under Firebase's 1,000-byte limit. + +## Why don't my new custom claims show up in the ID token? + +Tokens issued before the change keep the old claims until they expire, about an +hour later. Generate a new token on the *UID -> ID Token* tab, or force a +refresh on the client, for example `getIdToken(true)`. See +[When changes take effect](guide/custom-claims.md#when-changes-take-effect). + +## How do I get a Firebase App Check token for testing? + +Register a debug token for your app under **App Check** → **Manage debug +tokens** in the Firebase console, then paste it into the +[App Check](guide/app-check.md) tab and click **Exchange**. Send the result in +the `X-Firebase-AppCheck` header. This works for web, Android and iOS apps. + +## Can I use an API key restricted to an Android or iOS app? + +Yes. Select the Android or iOS app in the top bar and the app sends its package +name and SHA-1, or bundle ID, with each request, as the Firebase SDKs do. See +[API keys restricted to an app](firebase-setup.md#api-keys-restricted-to-an-app). + +## How do I decode a Firebase JWT? + +Every token the app shows has a **Decoded JWT claims** table underneath, with +`iat`, `exp` and `auth_time` converted to readable UTC times. The table shows +what a token says; it does not verify the signature. See +[Reading the results](guide/reading-results.md). + +## How long do the tokens last? + +Custom tokens and ID tokens last one hour. An App Check token lasts for the +time to live set in your App Check settings, shown as **TTL** under the token. +When a token expires, generate a new one. + +## Does it work with the Firebase Auth emulator? + +No. The app talks to Google's production endpoints for your project, so it needs +a real Firebase project. Use a development project rather than production; see +[Preparing your Firebase project](firebase-setup.md). + +## Which platforms does it run on? + +Linux (x86_64, glibc 2.35 or newer), Windows (x86_64) and macOS 11 or newer on +Apple Silicon or Intel. See [Installation](installation.md). + +## Is it free? + +Yes. It is open source under the MIT licence, and its source is on +[GitHub](https://github.com/smaranjit/firebase-token-toolkit). diff --git a/docs/src/introduction.md b/docs/src/introduction.md index cd1b7b0..c557259 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -3,7 +3,8 @@ Firebase Token Toolkit is a desktop app for getting the Firebase auth tokens you need while developing and testing a backend. Pick a user, click **Generate**, and you have a real ID token for that user, with its claims -decoded underneath and a **Copy** button next to it. +decoded underneath and a **Copy** button next to it. Paste it into Postman, +curl or your own tests to call any API that verifies Firebase ID tokens. ![Loading the project's apps, picking the Android app and a user, and generating an ID token](images/quick-start.gif) @@ -36,6 +37,8 @@ private key or the tokens it mints to disk. Android and iOS apps itself. 3. Follow the [Quick start](quick-start.md) to your first ID token. +Have a specific question? The [FAQ](faq.md) answers the common ones. + > **Use a development project.** A service-account key can sign in as any user > in its project, and the app shows real tokens on screen. Read the > [Security](security.md) page before pointing it at anything that matters.