Step 6: Server-Side Integration

⏱ 15 min read

Integrate Transcodes with your backend for enhanced security and control.

Why Server-Side Integration?

While the Auth Console Panel provides a quick no-code solution, server-side integration offers:

Enhanced Security: Validate tokens on your server
Custom Logic: Add business rules to authentication flow
Database Sync: Store user data in your own database
API Protection: Secure your API endpoints with token verification

How Token Verification Works

Client: Gets a JWT token from Transcodes after authentication
Client: Sends the token to your server in the Authorization header
Your Server: Downloads the public key from Transcodes (once, then cache it)
Your Server: Verifies the token locally using your language’s JWT library
No API calls to Transcodes are needed for verification - it’s all done locally!

Token Verification

Transcodes uses standard JWT tokens. You verify them locally on your server using the public key and your language’s native JWT library. No API calls to Transcodes are needed for verification.

Get the User Token

After authentication, retrieve the user’s token from Transcodes:


const token = await transcodes.token.getAccessToken();

Send Token to Your Server

Include the token in your API requests:


const response = await fetch('/api/protected', {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

Download the Public Key

Download the public key JSON file from the Transcodes dashboard and add it to your server:

Download Public Key JSON from Dashboard

Important: Download this JSON file and add it to your server as a static file

Caveat: If you generate a new public key JSON in the dashboard, the previous one will become invalid. Make sure to update the JSON file on your server whenever you generate a new key.

Install JWT Library

Install your language’s native JWT library:

Node.js


npm install jsonwebtoken jwks-rsa

Python


pip install pyjwt cryptography

Java


<!-- Maven -->
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-api</artifactId>
    <version>0.12.5</version>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-impl</artifactId>
    <version>0.12.5</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>io.jsonwebtoken</groupId>
    <artifactId>jjwt-jackson</artifactId>
    <version>0.12.5</version>
    <scope>runtime</scope>
</dependency>

Go


go get github.com/golang-jwt/jwt/v5

PHP


composer require firebase/php-jwt

Ruby


gem install jwt

Verify Token with Public Key

Use your language’s JWT library to verify tokens locally with the public key:

Node.js


// Node.js
const jwt = require('jsonwebtoken');
const jwksClient = require('jwks-rsa');
 
const client = jwksClient({
  jwksUri: 'https://cdn.transcodes.link/{YOUR_PROJECT_ID}/jwks.json',
  cache: true,
  cacheMaxAge: 86400000, // 24 hours
});
 
function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    const signingKey = key.getPublicKey();
    callback(null, signingKey);
  });
}
 
async function verifyToken(token) {
  return new Promise((resolve, reject) => {
    jwt.verify(token, getKey, {
      algorithms: ['RS256'],
      issuer: 'https://api.transcodes.io'
    }, (err, decoded) => {
      if (err) reject(err);
      else resolve(decoded);
    });
  });
}
 
// Usage
try {
  const payload = await verifyToken(token);
  console.log('User ID:', payload.sub);
  console.log('Email:', payload.email);
} catch (error) {
  console.error('Invalid token:', error.message);
}

Python


# Python
import jwt
import requests
from functools import lru_cache
 
@lru_cache(maxsize=1)
def get_public_keys():
    """Fetch and cache JWKS from Transcodes"""
    response = requests.get('https://api.transcodes.io/v1/.well-known/jwks.json')
    return response.json()
 
def verify_token(token: str) -> dict:
    """Verify JWT token locally"""
    jwks = get_public_keys()
 
    # Get the key ID from token header
    unverified_header = jwt.get_unverified_header(token)
    kid = unverified_header['kid']
 
    # Find the matching key
    public_key = None
    for key in jwks['keys']:
        if key['kid'] == kid:
            public_key = jwt.algorithms.RSAAlgorithm.from_jwk(key)
            break
 
    if not public_key:
        raise ValueError('Public key not found')
 
    # Verify and decode the token
    payload = jwt.decode(
        token,
        public_key,
        algorithms=['RS256'],
        issuer='https://api.transcodes.io'
    )
 
    return payload
 
# Usage
try:
    payload = verify_token(token)
    print(f"User ID: {payload['sub']}")
    print(f"Email: {payload['email']}")
except jwt.InvalidTokenError as e:
    print(f"Invalid token: {e}")

Java


// Java
import io.jsonwebtoken.*;
import io.jsonwebtoken.security.Keys;
import java.security.PublicKey;
import java.net.URL;
 
public class JwtValidator {
    private static final String JWKS_URL = "https://api.transcodes.io/v1/.well-known/jwks.json";
    private static final String ISSUER = "https://api.transcodes.io";
 
    private final JwkProvider jwkProvider;
 
    public JwtValidator() {
        this.jwkProvider = new UrlJwkProvider(new URL(JWKS_URL));
    }
 
    public Claims verifyToken(String token) throws JwtException {
        // Parse without validation to get kid
        String kid = Jwts.parserBuilder()
            .build()
            .parseClaimsJws(token)
            .getHeader()
            .getKeyId();
 
        // Get public key from JWKS
        Jwk jwk = jwkProvider.get(kid);
        PublicKey publicKey = jwk.getPublicKey();
 
        // Verify and parse token
        return Jwts.parserBuilder()
            .setSigningKey(publicKey)
            .requireIssuer(ISSUER)
            .build()
            .parseClaimsJws(token)
            .getBody();
    }
}
 
// Usage
JwtValidator validator = new JwtValidator();
try {
    Claims claims = validator.verifyToken(token);
    String userId = claims.getSubject();
    String email = claims.get("email", String.class);
    System.out.println("User: " + userId + ", Email: " + email);
} catch (JwtException e) {
    System.err.println("Invalid token: " + e.getMessage());
}

Go


// Go
package main
 
import (
    "encoding/json"
    "fmt"
    "net/http"
    "sync"
 
    "github.com/golang-jwt/jwt/v5"
)
 
type JWKSCache struct {
    keys map[string]interface{}
    mu   sync.RWMutex
}
 
var jwksCache = &JWKSCache{keys: make(map[string]interface{})}
 
func getPublicKey(kid string) (interface{}, error) {
    jwksCache.mu.RLock()
    if key, ok := jwksCache.keys[kid]; ok {
        jwksCache.mu.RUnlock()
        return key, nil
    }
    jwksCache.mu.RUnlock()
 
    // Fetch JWKS
    resp, err := http.Get("https://api.transcodes.io/v1/.well-known/jwks.json")
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
 
    var jwks struct {
        Keys []json.RawMessage `json:"keys"`
    }
    json.NewDecoder(resp.Body).Decode(&jwks)
 
    // Parse and cache keys
    // ... (key parsing logic)
 
    return jwksCache.keys[kid], nil
}
 
func verifyToken(tokenString string) (*jwt.Token, error) {
    return jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
        kid, ok := token.Header["kid"].(string)
        if !ok {
            return nil, fmt.Errorf("missing kid in token header")
        }
        return getPublicKey(kid)
    }, jwt.WithIssuer("https://api.transcodes.io"))
}
 
// Usage
token, err := verifyToken(tokenString)
if err != nil {
    fmt.Printf("Invalid token: %v\n", err)
    return
}
 
claims := token.Claims.(jwt.MapClaims)
fmt.Printf("User ID: %s\n", claims["sub"])
fmt.Printf("Email: %s\n", claims["email"])

PHP


<?php
// PHP
use Firebase\JWT\JWT;
use Firebase\JWT\JWK;
 
class JwtValidator {
    private const JWKS_URL = 'https://api.transcodes.io/v1/.well-known/jwks.json';
    private const ISSUER = 'https://api.transcodes.io';
 
    private static ?array $cachedKeys = null;
 
    public static function getPublicKeys(): array {
        if (self::$cachedKeys === null) {
            $jwks = json_decode(
                file_get_contents(self::JWKS_URL),
                true
            );
            self::$cachedKeys = JWK::parseKeySet($jwks);
        }
        return self::$cachedKeys;
    }
 
    public static function verifyToken(string $token): object {
        $keys = self::getPublicKeys();
 
        $decoded = JWT::decode($token, $keys);
 
        // Verify issuer
        if ($decoded->iss !== self::ISSUER) {
            throw new Exception('Invalid issuer');
        }
 
        return $decoded;
    }
}
 
// Usage
try {
    $payload = JwtValidator::verifyToken($token);
    echo "User ID: " . $payload->sub . "\n";
    echo "Email: " . $payload->email . "\n";
} catch (Exception $e) {
    echo "Invalid token: " . $e->getMessage() . "\n";
}

Ruby


# Ruby
require 'jwt'
require 'net/http'
require 'json'
 
class JwtValidator
  JWKS_URL = 'https://api.transcodes.io/v1/.well-known/jwks.json'
  ISSUER = 'https://api.transcodes.io'
 
  @@cached_keys = nil
 
  def self.get_public_keys
    return @@cached_keys if @@cached_keys
 
    uri = URI(JWKS_URL)
    response = Net::HTTP.get(uri)
    jwks = JSON.parse(response)
 
    @@cached_keys = jwks['keys'].each_with_object({}) do |key, hash|
      hash[key['kid']] = JWT::JWK.import(key).public_key
    end
  end
 
  def self.verify_token(token)
    keys = get_public_keys
 
    # Get kid from header
    header = JWT.decode(token, nil, false).last
    kid = header['kid']
 
    public_key = keys[kid]
    raise 'Unknown key ID' unless public_key
 
    payload, = JWT.decode(
      token,
      public_key,
      true,
      {
        algorithm: 'RS256',
        iss: ISSUER,
        verify_iss: true
      }
    )
 
    payload
  end
end
 
# Usage
begin
  payload = JwtValidator.verify_token(token)
  puts "User ID: #{payload['sub']}"
  puts "Email: #{payload['email']}"
rescue JWT::DecodeError => e
  puts "Invalid token: #{e.message}"
end

No API Calls Required: Token verification happens entirely on your server using the public key. No network calls to Transcodes are needed, making verification fast and reliable.

What’s Next

Server-side integration complete! Explore more: - API Reference - View all available APIs and methods