Authentication

Secure your application with TruSec authentication

Overview

TruSec provides multiple authentication methods to secure your applications. Choose the method that best fits your use case.

Authentication Methods

API Keys

Simple key-based authentication for server-to-server communication

OAuth 2.0

Industry-standard OAuth 2.0 flows for user authentication

JWT Tokens

Stateless JSON Web Tokens for scalable authentication

SSO / SAML

Enterprise single sign-on integration

API Key Authentication

Use API keys for server-side authentication. Include your secret key in the Authorization header:

curl -X GET https://api.trusec.io/v1/users \
  -H "Authorization: Bearer trusec_sk_1234567890abcdef"

Never expose your secret API key in client-side code. Use public keys for browser-based applications.

Key Types

Type	Prefix	Use Case
Secret Key	trusec_sk_	Server-side API calls
Public Key	trusec_pk_	Client-side SDK initialization
Test Key	trusec_test_	Development and testing

OAuth 2.0

TruSec supports standard OAuth 2.0 flows:

Authorization Code Flow

// Step 1: Redirect user to authorization URL
const authUrl = trusec.oauth.getAuthorizationUrl({
  redirectUri: 'https://yourapp.com/callback',
  scope: ['read:users', 'write:policies'],
  state: generateRandomState(),
});

// Step 2: Exchange code for tokens
const tokens = await trusec.oauth.exchangeCode({
  code: req.query.code,
  redirectUri: 'https://yourapp.com/callback',
});

// Step 3: Use the access token
const user = await trusec.users.me({
  accessToken: tokens.accessToken,
});

PKCE Flow

For mobile and single-page applications, use PKCE for enhanced security:

import { generateCodeVerifier, generateCodeChallenge } from '@trusec/sdk';

const codeVerifier = generateCodeVerifier();
const codeChallenge = await generateCodeChallenge(codeVerifier);

const authUrl = trusec.oauth.getAuthorizationUrl({
  redirectUri: 'https://yourapp.com/callback',
  codeChallenge,
  codeChallengeMethod: 'S256',
});

Session Management

Create a Session

const session = await trusec.sessions.create({
  userId: 'user_123',
  expiresIn: '24h',
  metadata: {
    device: 'Chrome on macOS',
    ip: '192.168.1.1',
  },
});

Verify a Session

const result = await trusec.sessions.verify({
  token: sessionToken,
});

if (result.valid) {
  // Session is valid
  const user = result.user;
} else {
  // Session expired or invalid
  redirectToLogin();
}

Revoke a Session

await trusec.sessions.revoke({
  token: sessionToken,
});

Best Practices

Rotate API keys regularly

Set up automatic key rotation every 90 days to minimize the impact of potential key exposure.

Use environment variables

Never hardcode API keys. Use environment variables or a secrets manager.

Implement rate limiting

Protect your endpoints with rate limiting to prevent brute-force attacks.

Enable audit logging

Track all authentication events for security monitoring and compliance.