JWT & API Setup

Crunchyroll Downloader — Practical Scripting
Course 1 · Chapter 1 · JWT & API Setup

🔐 JWT & API Setup

This chapter teaches you about JWT (JSON Web Tokens), how they work, and how to set up your project to authenticate with the Crunchyroll API. JWT is used by many modern web services for secure, stateless authentication.

🔑 What is JWT?

JWT stands for JSON Web Token. It's a secure way to prove your identity to an API without sending your password every time.

How JWT Works

Step What Happens
1. Login Send username/password to API
2. API validates Server checks credentials
3. Token issued Server sends back JWT token
4. Store token You save the token locally
5. Use token Send token in header for requests: Authorization: Bearer TOKEN
6. Token expires Token has expiration time (usually hours)

JWT Structure

A JWT looks like: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

It has 3 parts separated by dots:

  1. Header: Type of token (JWT) and algorithm
  2. Payload: Your actual data (user ID, username, etc.)
  3. Signature: Server's signature to prove it's legitimate

📁 Project Structure

crunchy-downloader/
├── .env                      ← Username/password (kept secret!)
├── .env.example              ← Template for others
├── requirements.txt          ← Python dependencies
├── config.py                 ← Configuration management
├── crunchyroll_utils.py      ← API utility functions
├── download.py               ← Main download script
├── token_cache.json          ← Cached JWT token (gitignore!)
└── .gitignore                ← Don't commit secrets!

📦 Dependencies

Create requirements.txt:

requests==2.31.0
python-dotenv==1.0.0

Install them:

pip install -r requirements.txt

🔒 Storing Credentials Safely

Create .env.example (template — share this):

# Crunchyroll credentials
CRUNCHYROLL_EMAIL=your-email@example.com
CRUNCHYROLL_PASSWORD=your-password

# API settings
API_BASE_URL=https://api.crunchyroll.com
TOKEN_CACHE_FILE=token_cache.json

Create .env (YOUR actual credentials — never commit!):

# Crunchyroll credentials
CRUNCHYROLL_EMAIL=emubantam@gmail.com
CRUNCHYROLL_PASSWORD=mypassword123

# API settings
API_BASE_URL=https://api.crunchyroll.com
TOKEN_CACHE_FILE=token_cache.json

Create .gitignore:

# Secrets
.env
token_cache.json
credentials.json

# Python
__pycache__/
*.pyc

# IDE
.vscode/
.idea/

🌐 Understanding the Crunchyroll API

Crunchyroll's API requires:

  • Login with email/password → get JWT token
  • Use token in request header: Authorization: Bearer {token}
  • Fetch episodes from /api/v2/episodes endpoint
  • Handle token expiration and refresh

💻 Coding Challenges

Challenge 1: Project Setup

Set up the complete project structure:

  1. Create crunchy-downloader/ directory
  2. Create .env and .env.example files
  3. Create requirements.txt with dependencies
  4. Create .gitignore with appropriate entries

Goal: Complete the project setup.

Challenge 2: JWT Decoding

Understand JWT structure:

  1. Get a JWT token string
  2. Decode the payload (base64 decode middle part)
  3. Extract user information
  4. Check expiration timestamp

Goal: Understand JWT internals.

Challenge 3: HTTP Headers with JWT

Make authenticated HTTP requests:

  1. Create sample JWT token
  2. Create HTTP headers with Authorization: Bearer {token}
  3. Test request to sample API
  4. Verify token is sent correctly

Goal: Learn JWT-based API authentication.