Skip to main content
Spoo.me uses JWT (JSON Web Tokens) for authentication and supports multiple OAuth providers for user login. This guide will walk you through setting up authentication for your self-hosted instance.
Authentication is required for users to access v1 API features like URL management, API key creation, and private statistics.

​
JWT Configuration

JWT tokens are used to authenticate users after they log in via OAuth or other methods.

​
Generate RSA Key Pair

You’ll need to generate an RSA key pair for signing and verifying JWT tokens.
1

Generate Private Key

Generate a 2048-bit RSA private key:
2

Generate Public Key

Extract the public key from the private key:
3

View Keys

Display the keys in a format suitable for environment variables:

​
Configure JWT Environment Variables

Add the following to your .env file:
Security Notes:
  • Keep your JWT_PRIVATE_KEY secret and never commit it to version control
  • Set COOKIE_SECURE=true in production to ensure cookies are only sent over HTTPS
  • Store keys securely using environment variables or secret management services

​
OAuth Configuration

Spoo.me supports three OAuth providers: Google, GitHub, and Discord. You can enable one or all of them.

​
Google OAuth

1

Create Google Cloud Project

  1. Go to Google Cloud Console
  2. Create a new project (or select an existing one)
  3. Click Create Project and give it a name (e.g., “Spoo.me OAuth”)
2

Enable Google+ API

  1. In the left sidebar, go to APIs & Services → Library
  2. Search for “Google+ API”
  3. Click Enable
3

Configure OAuth Consent Screen

  1. Go to OAuth consent screen in the left sidebar
  2. Select External (or Internal if using Google Workspace)
  3. Fill in the required information:
    • App name: Your app name (e.g., “Spoo.me”)
    • User support email: Your email
    • Developer contact: Your email
  4. Add authorized domains:
    • For local dev: localhost and 127.0.0.1
    • For production: Your domain (e.g., yourdomain.com)
  5. Click Save and Continue
4

Create OAuth Credentials

  1. Go to Credentials in the left sidebar
  2. Click Create Credentials → OAuth 2.0 Client ID
  3. Select Web application
  4. Add Authorized redirect URIs:
  5. Click Create
  6. Copy the Client ID and Client Secret
5

Add to Environment Variables

For production, change the redirect URI to your domain:

​
GitHub OAuth

1

Create GitHub OAuth App

  1. Go to GitHub Developer Settings
  2. Click New OAuth App
  3. Fill in the application details:
    • Application name: Your app name (e.g., “Spoo.me”)
    • Homepage URL:
      • Local: http://127.0.0.1:8000 or http://localhost:8000
      • Production: https://yourdomain.com
    • Authorization callback URL:
      • Local: http://127.0.0.1:8000/oauth/github/callback
      • Production: https://yourdomain.com/oauth/github/callback
  4. Click Register application
2

Get Credentials

  1. Copy the Client ID
  2. Click Generate a new client secret
  3. Copy the Client Secret (you won’t be able to see it again)
3

Add to Environment Variables

For production:

​
Discord OAuth

1

Create Discord Application

  1. Go to Discord Developer Portal
  2. Click New Application
  3. Give it a name (e.g., “Spoo.me”)
  4. Click Create
2

Configure OAuth2

  1. Go to the OAuth2 section in the left sidebar
  2. Click Add Redirect under Redirects
  3. Add your redirect URIs:
  4. Click Save Changes
3

Get Credentials

  1. In the OAuth2 section, copy the Client ID
  2. Click Reset Secret to generate a new client secret
  3. Copy the Client Secret
4

Add to Environment Variables

For production:

​
Complete Environment Configuration

Here’s a complete example .env configuration with all authentication settings:

​
Testing Authentication

After configuration, test the authentication flow:
1

Start Your Application

2

Access Login Page

Navigate to http://127.0.0.1:8000/login in your browser
3

Test OAuth Login

Click on any OAuth provider button (Google, GitHub, or Discord) and complete the authentication flow
4

Verify Dashboard Access

After successful login, you should be redirected to the dashboard at http://127.0.0.1:8000/dashboard

​
Troubleshooting

Error: redirect_uri_mismatch or invalid_redirect_uriSolution:
  • Ensure the redirect URI in your OAuth provider settings exactly matches the one in your .env file
  • Check for trailing slashes (some providers are strict about this)
  • Use http:// for local development and https:// for production
Error: Invalid token or Token verification failedSolution:
  • Ensure your JWT_PRIVATE_KEY and JWT_PUBLIC_KEY are correctly formatted with \n for newlines
  • Verify that both keys are from the same RSA key pair
  • Check that JWT_ISSUER and JWT_AUDIENCE match in your configuration
Error: OAuth buttons not showing on login pageSolution:
  • Verify that all three environment variables for the provider are set (CLIENT_ID, CLIENT_SECRET, REDIRECT_URI)
  • Check application logs for any configuration errors
  • Restart the application after updating .env file