Security Best Practices

This guide covers credential management, environment requirements, and secure integration patterns for all YorAuth SDKs and APIs. Following these practices protects your application and your users' data.

SDK Environment Requirements

Each YorAuth SDK is designed for a specific runtime environment. Using an SDK in the wrong environment can expose credentials to unauthorized parties.

Credential Types and Safety

Not all credentials are equal. Some are safe for client-side use; others must never leave your server.

Common Mistakes to Avoid

DO NOT: Use API keys in client-side code

// WRONG -- API key will be bundled into browser JavaScript
const yorauth = new YorAuth({
  applicationId: 'your-app-id',
  baseUrl: 'https://api.yorauth.com',
  apiKey: 'ya_sk_live_abc123...', // EXPOSED TO ANYONE WHO VIEWS YOUR PAGE
});

DO: Use JWT tokens from login for client-side authentication

// CORRECT -- JWT obtained via secure login flow
const yorauth = new YorAuth({
  applicationId: 'your-app-id',
  baseUrl: 'https://api.yorauth.com',
});

// Authenticate the user, then use the returned JWT
const { accessToken } = await yorauth.auth.login({
  email: 'user@example.com',
  password: 'their-password',
});
yorauth.setAccessToken(accessToken);

DO NOT: Expose secrets through environment variable prefixes

# WRONG (Next.js) -- NEXT_PUBLIC_ variables are bundled into client code
NEXT_PUBLIC_YORAUTH_API_KEY=ya_sk_live_abc123

# CORRECT (Next.js) -- no prefix means server-only
YORAUTH_API_KEY=ya_sk_live_abc123

# WRONG (Nuxt) -- NUXT_PUBLIC_ variables are sent to the client
NUXT_PUBLIC_YORAUTH_API_KEY=ya_sk_live_abc123

# CORRECT (Nuxt) -- use NUXT_ (without PUBLIC) for server-only
NUXT_YORAUTH_API_KEY=ya_sk_live_abc123

DO: Keep API key operations on the server

// app/api/yorauth/users/route.ts -- Server-only API route
import { YorAuth } from '@yorauth/js-sdk';

const yorauth = new YorAuth({
  applicationId: process.env.YORAUTH_APP_ID!,
  baseUrl: process.env.YORAUTH_BASE_URL!,
  apiKey: process.env.YORAUTH_API_KEY!, // Server-only env var
});

export async function GET() {
  const users = await yorauth.users.list();
  return Response.json(users);
}

// server/api/yorauth/users.ts -- Server-only API route
import { YorAuth } from '@yorauth/js-sdk';

const yorauth = new YorAuth({
  applicationId: useRuntimeConfig().yorauthAppId,
  baseUrl: useRuntimeConfig().yorauthBaseUrl,
  apiKey: useRuntimeConfig().yorauthApiKey, // Server-only runtime config
});

export default defineEventHandler(async () => {
  return await yorauth.users.list();
});

OIDC/PKCE for Client-Side Authentication

If your application is a single-page app (SPA) without server-side rendering, use the OIDC Authorization Code flow with PKCE. This flow is designed for public clients and does not require a client secret.

1. Register an OIDC client in the YorAuth Dashboard.
2. Initiate the authorization flow by redirecting the user to your YorAuth authorization endpoint with a PKCE code_challenge.
3. Exchange the authorization code for tokens at the /oidc/token endpoint using the code_verifier (no client secret needed for public clients).
4. Use the access token for authenticated API requests.

See Authorization Flow and Token Endpoint for full details.

API Key Rotation

Rotate API keys regularly and immediately if you suspect exposure.

1. Create a new API key in the YorAuth Dashboard or via the API.
2. Update your server environment with the new key.
3. Verify that your application works with the new key.
4. Revoke the old key once you have confirmed the new key is working.

Webhook Signature Verification

Every webhook delivery from YorAuth includes an X-YorAuth-Signature header containing an HMAC-SHA256 signature. Always verify this signature before processing the webhook payload.

const crypto = require('crypto');

function verifyWebhookSignature(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader, 'utf8'),
    Buffer.from(expected, 'utf8')
  );
}

Never skip signature verification. Without it, anyone can send fabricated events to your webhook endpoint.

See Webhook Security for complete verification examples in JavaScript, PHP, and Python.

Environment Variable Best Practices

• Never commit .env files to version control. Add .env to your .gitignore.
• Use a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler) in production.
• Use separate credentials for development, staging, and production environments.
• Restrict access to environment variables in your CI/CD pipeline to only the jobs that need them.
• Audit regularly -- review which team members and services have access to production credentials.

Runtime Security Features

The @yorauth/js-sdk includes built-in browser environment detection. If you initialize the SDK with an API key in a browser environment, it will throw an error:

YorAuth SECURITY ERROR: API key authentication detected in a browser environment.

This is a safety net, not a substitute for proper architecture. Design your application so that API keys are only ever loaded in server-side code.

Further Reading

• Webhook Security -- Signature verification, replay protection
• OIDC Authorization Flow -- Secure auth flows with PKCE
• Token Management -- JWT lifecycle and refresh
• Terms of Service -- SDK usage obligations