Pocket ID

Use Pocket ID as an OIDC provider to let people sign in to Chatto with their Pocket ID passkeys. Chatto uses Pocket ID’s issuer discovery, client ID, and client secret; you do not need to enter its individual authorization or token endpoints.

Learn more about Pocket ID on the Pocket ID website.

Using another identity provider?

See External Login Providers for generic OIDC configuration and other self-hosted options.

This guide uses these example URLs:

Service	Public URL
Chatto	https://chat.example.com
Pocket ID	https://id.example.com

Both services should use HTTPS and must be able to reach each other at their public URLs.

1. Create the Pocket ID client

   Sign in to Pocket ID as an administrator, open OIDC Clients, and select Add OIDC Client. Pocket ID’s OIDC client documentation describes the client ID and secret used by confidential applications such as Chatto.

   Configure the client with:

   Field	Value
   Name	Chatto
   Callback URL	https://chat.example.com/auth/providers/pocket-id/callback
   Client Launch URL	https://chat.example.com (optional)

   Keep the callback URL exact, including the https scheme and the pocket-id provider ID. Pocket ID lists a mismatched scheme or callback URL as a common cause of OIDC failures.

   Save the client, then copy its Client ID and Client Secret. Store the secret securely; Chatto needs it when exchanging an authorization code with Pocket ID.

2. Allow Pocket ID users to access the client

   Open the new client’s Allowed User Groups section and choose one of these options:

   • Select one or more groups to limit Chatto login to their members.
   • Select Unrestrict to allow every Pocket ID user to access Chatto.

   Pocket ID denies everyone access to a newly created OIDC client until you configure this setting. See Allowed User Groups in the Pocket ID documentation.

   Note

   Pocket ID groups control who may authenticate through this client. They do not assign Chatto roles or permissions.

3. Configure Chatto

   Set Chatto’s public URL and add Pocket ID as an OIDC provider. Use the public base URL of your Pocket ID instance as issuer_url, without /.well-known/openid-configuration.

   chatto.toml

   [webserver]
   url = "https://chat.example.com"
   
   [[auth.providers]]
   id = "pocket-id"
   type = "oidc"
   label = "Pocket ID"
   issuer_url = "https://id.example.com"
   client_id = "<pocket-id-client-id>"
   client_secret = "<generate-me>"
   auto_provision = false

   Replace <generate-me> with the client secret generated by Pocket ID.

   Environment variables

   CHATTO_WEBSERVER_URL=https://chat.example.com
   CHATTO_AUTH_PROVIDERS_0_ID=pocket-id
   CHATTO_AUTH_PROVIDERS_0_TYPE=oidc
   CHATTO_AUTH_PROVIDERS_0_LABEL="Pocket ID"
   CHATTO_AUTH_PROVIDERS_0_ISSUER_URL=https://id.example.com
   CHATTO_AUTH_PROVIDERS_0_CLIENT_ID=<pocket-id-client-id>
   CHATTO_AUTH_PROVIDERS_0_CLIENT_SECRET=<generate-me>
   CHATTO_AUTH_PROVIDERS_0_AUTO_PROVISION=false

   Replace <generate-me> with the client secret generated by Pocket ID. Provider indexes start at 0 and must not contain gaps.

   Keep id = "pocket-id" stable after people link accounts. Changing it also changes the callback URL and strands existing external identity links.

4. Choose how accounts are created

   auto_provision controls what happens when a Pocket ID identity is not linked to a Chatto account:

   • Keep auto_provision = false for an existing or invite-only server. Each person first signs in with their existing Chatto account and links Pocket ID from account settings.
   • Set auto_provision = true if every Pocket ID user allowed in step 2 should be able to create an account. After the first Pocket ID login, Chatto asks the person to confirm a username before creating it.

   Chatto matches the account by Pocket ID issuer and subject. It never merges accounts automatically by email address.

5. Restart and test Chatto

   Restart the Chatto server after changing its configuration. Open its login page and select Pocket ID.

   If auto_provision is disabled, test by signing in to an existing Chatto account, linking Pocket ID in account settings, signing out, and then using the Pocket ID login button.

Request email claims

Chatto only requests the openid and profile scopes by default. Pocket ID login works without an email address because Chatto identifies the linked account by the OIDC issuer and subject.

To also request an email claim, add:

request_email = true

Or set:

CHATTO_AUTH_PROVIDERS_0_REQUEST_EMAIL=true

Chatto stores the address as a verified email only when Pocket ID returns both an email and an explicit email_verified = true claim. A verified email can be used for password reset and owner promotion; it is not used to choose an existing account.

Troubleshooting

Symptom	Check
Pocket ID rejects the callback	The Pocket ID callback URL exactly matches https://chat.example.com/auth/providers/pocket-id/callback, and Chatto’s webserver.url is its public HTTPS URL.
Pocket ID says the user is not allowed	The client has selected Allowed User Groups, or access is set to Unrestrict.
Chatto cannot discover the provider	issuer_url is Pocket ID’s reachable public base URL, with no discovery-path suffix. Pocket ID’s APP_URL must also reflect that public URL.
Chatto refuses to create an account	Enable auto_provision, or sign in to an existing account and link Pocket ID first.
Login worked before the provider ID changed	Restore the original id = "pocket-id" and its matching callback URL.

Related guides

External Login Providers Provider IDs, scopes, account linking, and discovery behavior.

Identity & Login Plan account creation, recovery, and owner access.

Environment Variables Reference for Chatto's provider environment variables.