Token Security

Secure handling of OAuth tokens.

---

Token Types

Token	Purpose	Lifetime	Storage
Access	API authorization	1 hour	HttpOnly cookie
Refresh	Obtain new access	30 days	HttpOnly cookie
ID	User identity	1 hour	Memory only

---

Secure Storage

Recommended: HttpOnly Cookies

The SDK stores tokens in HttpOnly cookies:

Cookie: syauth_access_token=eyJ...
        syauth_refresh_token=def...

Benefits:

• Cannot be accessed by JavaScript
• Automatic CSRF protection with SameSite
• Secure flag requires HTTPS

Not Recommended: localStorage

Never store tokens in localStorage:

// ❌ NEVER do this
localStorage.setItem('access_token', token);

Risks:

• XSS attacks can steal tokens
• Persists beyond session
• No expiration control

---

Token Transmission

Authorization Header

fetch('/api/resource', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

Always Use HTTPS

Environment	URL
Development	http://localhost:3000 (local only)
Production	https://yourapp.com

---

Token Validation

Server-Side Validation

Always validate tokens on your backend:

async function validateToken(accessToken: string) {
  const response = await fetch('https://api.syauth.com/e/v1/oauth/userinfo', {
    headers: { 'Authorization': `Bearer ${accessToken}` }
  });
  
  if (!response.ok) {
    throw new Error('Invalid token');
  }
  
  return response.json();
}

JWT Validation

For local validation without API call:

import jwt from 'jsonwebtoken';

function validateJWT(token: string) {
  try {
    const decoded = jwt.verify(token, publicKey, {
      algorithms: ['RS256'],
      audience: process.env.SYAUTH_CLIENT_ID,
      issuer: 'https://api.syauth.com/e/v1'
    });
    return decoded;
  } catch (error) {
    return null;
  }
}

---

Token Refresh

Automatic (SDK)

The SDK refreshes tokens automatically:

const { getAccessToken } = useSyAuth();

// Always returns a valid token (refreshes if needed)
const token = await getAccessToken();

Manual (API)

POST https://api.syauth.com/e/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=current_refresh_token
&client_id=xxx

---

Token Revocation

Single Token

POST https://api.syauth.com/e/v1/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=token_to_revoke
&client_id=xxx

All User Tokens

Use the Dashboard or API to revoke all tokens for a user.

---

Token Denylist

SyAuth maintains a token denylist for:

• Explicitly revoked tokens
• Tokens from password changes
• Tokens from security events

Denylisted tokens are rejected immediately.

---

Security Checklist

• Tokens stored in HttpOnly cookies
• Never log tokens
• Validate tokens server-side
• Use short access token lifetimes
• Implement token refresh
• Handle token revocation
• Monitor token usage

---

Next Steps

• PKCE Explained - Authorization code security
• Best Practices - General security