Frontend Token Route

Your frontend needs a way to get short-lived tokens to fetch events from the Archiva API. The SDK provides a ready-made route handler that does this securely.

Why This Route Is Needed

The problem: You want to show events in your frontend, but you can't expose your API key to the browser (that would be a security risk).

The solution: Create a server-side API route that uses your API key to generate temporary tokens. Your frontend calls this route, gets a token, and uses that token to fetch events. The tokens expire quickly (90 seconds), so even if intercepted, they're only useful for a short time.

Basic Setup

Create a Next.js API route in your app directory:

File: app/api/archiva/frontend-token/route.ts

import { GET } from '@archiva/archiva-nextjs/server';

// Export the GET handler - that's it!
export { GET };

This simple route handler:

  • Uses your ARCHIVA_SECRET_KEY (which stays on the server)
  • Generates a short-lived JWT token (90 seconds)
  • Returns the token to your frontend
  • Handles all the authentication details for you

How It Works

When your frontend needs a token:

  1. A client component calls useArchiva().getToken()
  2. The SDK checks if there's a valid cached token
  3. If not, it makes a GET request to /api/archiva/frontend-token
  4. Your route handler uses ARCHIVA_SECRET_KEY to request a token from Archiva
  5. Archiva returns a JWT token with 90-second expiry
  6. The token is returned to your frontend and cached
  7. The frontend uses the token to fetch events

Security benefits:

  • Your API key never leaves your server
  • Tokens expire quickly (90 seconds)
  • Tokens are read-only (can't create events)
  • Tokens are scoped to your project
  • Even if intercepted, tokens are only useful briefly

Custom Configuration

If you need to customize the API base URL or other settings, use the createFrontendTokenRoute function:

import { createFrontendTokenRoute } from '@archiva/archiva-nextjs/server';

export const GET = createFrontendTokenRoute({
  apiBaseUrl: process.env.ARCHIVA_API_URL, // Optional: defaults to https://api.archiva.app
});

Configuration Options

OptionTypeDefaultDescription
apiBaseUrlstring'https://api.archiva.app'Base URL for the Archiva API

Project-Scoped Tokens

If you want tokens scoped to a specific project, you can pass the projectId as a query parameter:

// Frontend can call: GET /api/archiva/frontend-token?projectId=proj_123

Or configure it in the ArchivaProvider component, which will automatically pass it to the token endpoint.

Troubleshooting

Route returns 401 Unauthorized

This means your ARCHIVA_SECRET_KEY is either:

  • Not set in your environment variables
  • Invalid or revoked
  • Not accessible to the route handler

Solutions:

  1. Verify ARCHIVA_SECRET_KEY is set in .env.local
  2. Restart your Next.js dev server
  3. Check that the API key is valid and active
  4. Ensure the route file is in the correct location: app/api/archiva/frontend-token/route.ts

Route not found (404)

Make sure:

  • The file is at app/api/archiva/frontend-token/route.ts (App Router) or pages/api/archiva/frontend-token.ts (Pages Router)
  • The route handler is exported correctly: export { GET }
  • Your Next.js server has been restarted after creating the file

Token generation fails

If token generation fails, check:

  • Your ARCHIVA_SECRET_KEY is valid
  • The Archiva API is accessible from your server
  • Your network/firewall allows outbound HTTPS requests to api.archiva.app

Security Best Practices

  1. Never expose your API key - Keep ARCHIVA_SECRET_KEY in environment variables only
  2. Use HTTPS in production - Ensure your token endpoint is only accessible over HTTPS
  3. Monitor token usage - Watch for unusual patterns that might indicate abuse
  4. Rotate keys regularly - Periodically rotate your API keys for better security

Next Steps