Personal Google authorization

Set up Castles for Gmail

Create one Google Desktop OAuth client in a project you control, then let Castles keep a private managed copy and open Google’s authorization page. No Google password or mailbox data passes through Castles infrastructure.

1. What you are creating

The OAuth client identifies your own Google Cloud project when the local Castles process asks Google for authorization. It does not give the Castles maintainer access to your project, account, or mail. Castles uses the client only for direct local authorization with Google; there is no Castles backend.

A desktop application cannot keep a client secret confidential from someone who controls the installed application. Even so, treat the downloaded client JSON as sensitive configuration: keep it private and never post it in source control, issues, screenshots, email, or chat.

2. Before starting

You need:

• a Google account;
• Castles installed;
• access to the Google Cloud Console;
• a browser; and
• a private local place for the downloaded JSON.

3. Create a dedicated project

1. Open Google Cloud Console and create a project, or select a dedicated project you already control.
2. Use a clear personal name such as Castles Personal. The exact name does not matter.

A dedicated project keeps Castles’ API, consent, client, and grant settings separate from unrelated applications and credentials. Do not mix unrelated APIs or credentials into this project.

See Google’s official project creation documentation.

4. Enable the Gmail API

1. With the dedicated project selected, open the Google API Library.
2. Search for Gmail API, open it, and choose Enable.

Google documents the current API Library process in its official OAuth configuration guidance.

5. Configure the OAuth application

Open Google Auth Platform for the selected project and choose Get started if the application has not been configured. Google currently organizes these settings under Branding, Audience, Clients, and Data Access.

• For a personal Google account, choose an External audience.
• Internal is available only for an appropriate Google Workspace organization and restricts access to that organization.
• Use an app name you control, such as Castles Personal.
• Choose a user support address you monitor and developer contact addresses you control.
• Do not impersonate the public Castles project and do not claim Google verification or endorsement.

A personal desktop client does not need Castles’ public logo, website, privacy page, or domain merely to follow this guide unless Google’s current console specifically requires a field for your configuration. Review Google’s official Google Auth Platform setup documentation if the interface changes.

6. Add data access

On Data Access, add exactly this scope:

https://www.googleapis.com/auth/gmail.readonly

Castles must read message content to discover relationship evidence in visible wording, headers, and link hostnames. Metadata-only access is insufficient for this function.

Read-only access does not allow Castles to send, modify, delete, label, move, draft, or compose mail.

Do not manually add openid, email, profile, gmail.metadata, gmail.modify, mail.google.com, or any other scope. If Google displays basic identity permissions that it manages automatically, distinguish those interface defaults from the one Gmail scope Castles explicitly requests; do not expand access manually.

See Google’s official Data Access documentation.

7. Choose Testing or In production

Testing

Testing is appropriate for initial setup and experimentation. Only accounts explicitly listed as test users can authorize. Add the Google account you will use with Castles to the test-user list.

For an application requesting this Gmail scope, a Testing authorization currently expires seven days after consent; an offline refresh token also expires. You may need to run setup again.

In production for a personal client

Moving an External project to In production removes the Testing test-user allowlist behavior and Testing’s seven-day authorization expiration. It does not mean Google has verified, approved, or endorsed the application. An unverified-app warning may appear, and Google’s unverified-app user cap and other current requirements still apply.

Use an unverified In production client only for yourself or a small number of people who personally trust and can verify the project owner. Public distribution has separate verification, quota, policy, and possibly security-assessment requirements. This guide does not recommend publishing an unverified client to unknown users.

Before changing status, review Google’s official Audience and publishing-status documentation and unverified-app guidance.

8. Create a Desktop app client

1. Open Google Auth Platform → Clients.
2. Choose Create client.
3. Set application type to Desktop app.
4. Use a clear personal name and create the client.
5. Download the JSON immediately and keep it private.

Do not use a Web application client, service account, or API key. Google’s desktop client uses a local loopback redirect; Castles binds only to 127.0.0.1 on a temporary port.

See Google’s official OAuth Clients documentation and desktop authorization documentation.

9. Run Castles setup

Run the normal guided command:

castles setup

Castles reuses a valid managed client when one exists. Otherwise, in an interactive terminal it checks only immediate files in your Downloads directory, validates conventional Google client JSON candidates, and asks before using one. Multiple valid files always require an explicit choice. If none is found, Castles asks for the downloaded file’s path.

Advanced users can supply the path directly; this bypasses discovery and prompts:

castles setup /private/path/to/google-desktop-client.json

After validation, Castles writes a normalized private managed copy in its platform-native configuration directory. On POSIX systems the directory is mode 0700 and the file is mode 0600. The source is not deleted and its path is not stored.

Only if the browser cannot be opened, retry with:

castles setup --no-browser

This prints a sensitive, one-attempt authorization URL. Open only the newest URL and never share it or put it in an issue, screenshot, shell transcript, or chat.

10. Google warning screens

A personal unverified client may display an unverified-app warning. Continue only when the Google Cloud project and OAuth client are yours or are controlled by someone you personally trust. Verify the project identity shown by Google before granting access.

Do not use warning-screen instructions to persuade unknown users to trust a project. Public Castles does not ask users to trust a shared unverified client; each user supplies and owns their client.

11. After setup

Successful setup saves authorization but does not scan Gmail. Start analysis explicitly:

castles scan
castles results

12. Revocation and deletion

• castles logout removes the local authorization token only. It does not revoke the Google grant, delete findings, or delete the managed client.
• Remove the project’s access on the Google Account third-party connections page to revoke the Google grant.
• Delete local findings or all Castles configuration/state using the platform-specific instructions in the privacy policy.
• The original downloaded JSON and Castles’ managed client are separate. Castles never deletes the source. The managed client remains until you manually remove the Castles configuration directory; there is currently no command that removes it.

13. Troubleshooting

The project is in Testing

Confirm the authorizing account is listed under Audience → Test users. Testing authorization for this Gmail scope expires after seven days, so reauthorization is expected. Review the Testing or In production section.

The JSON type is wrong

Create a new client whose application type is Desktop app. A Web client, service account, API key, token file, or arbitrary credentials file will be rejected.

An old authorization tab was used

Close tabs from earlier attempts and start setup again. Every attempt has a new state value and PKCE verifier; only the newest tab can complete the current listener.

The browser cannot reach 127.0.0.1

Keep the Castles command running while Google redirects. Local firewall controls, hardened browser settings, privacy extensions, containers, or remote-shell boundaries can block the loopback connection. Allow the local redirect or retry in a standard browser environment. Castles does not bypass browser controls.

The callback times out

Castles waits five minutes. A timeout does not reveal one exact cause. Authorization may not have been completed, an old tab may have been used, browser controls may have blocked the redirect, a Testing account may not be allowed, or Google may have denied the application before callback. Start a new attempt.

Multiple Downloads candidates appear

Castles will not choose silently. Select the intended numbered file, cancel and move unrelated client files elsewhere, or pass the intended path explicitly.

The browser does not open

Use castles setup --no-browser and open the printed newest URL yourself. The loopback listener must still be reachable on the same machine.

Replacing existing authorization

Use castles setup --force to require a fresh Google authorization. A failed, denied, cancelled, malformed, or incomplete attempt preserves the prior token. A successful exchange with the exact required scope replaces it atomically.

Revoke and retry

Run castles logout, revoke the grant in Google Account third-party connections if desired, then run setup again. Removing the local token and revoking the Google grant are separate actions.