Token Lifecycle

Guardhouse uses industry-standard OAuth 2.0 and OpenID Connect (OIDC) protocols for authentication and authorization. Understanding the different types of tokens and their lifecycle is essential for building secure applications.

Token Types

Access Token

An access token is a bearer token that authorizes access to protected resources (APIs).

• Purpose: Grants access to API resources
• Format: JSON Web Token (JWT)
• Lifetime: Short-lived (typically 15-60 minutes)
• Usage: Included in the Authorization header as Bearer <access_token>

Example Usage:

GET /api/users
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

ID Token

An ID token contains identity information about the authenticated user.

• Purpose: Provides user profile information
• Format: JWT
• Lifetime: Short-lived (matches access token lifetime)
• Usage: Used by client applications to authenticate users and access user claims

Standard Claims:

• sub - Subject (unique user identifier)
• iss - Issuer (Guardhouse domain)
• aud - Audience (client ID)
• exp - Expiration time
• iat - Issued at time
• email - User email
• name - User full name

Refresh Token

A refresh token is a long-lived token used to obtain new access tokens without requiring user re-authentication.

• Purpose: Obtain new access tokens without user interaction
• Format: Opaque token or JWT (depending on client configuration)
• Lifetime: Long-lived (days, weeks, or months)
• Usage: Stored securely and used to request new access tokens

Example Token Refresh Request:

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=your_refresh_token
&client_id=your_client_id
&client_secret=your_client_secret

Token Lifecycle Flow

1. User Authentication

User → Guardhouse Login → Access Token + ID Token + Refresh Token

When a user authenticates successfully, Guardhouse issues:

• An access token (for API calls)
• An ID token (for user identity)
• A refresh token (for token renewal)

2. Using Access Tokens

Access tokens are used to make authenticated requests to your APIs:

// Using the access token in an API request
const response = await fetch('https://api.example.com/users', {
  headers: {
    'Authorization': `Bearer ${accessToken}`
  }
});

3. Token Refresh

When an access token expires, use the refresh token to obtain a new one:

// Refreshing the access token
const response = await fetch('https://your-guardhouse-domain/oauth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'refresh_token',
    refresh_token: refreshToken,
    client_id: clientId,
    client_secret: clientSecret,
  }),
});

const data = await response.json();
const newAccessToken = data.access_token;

4. Token Expiration & Re-authentication

If a refresh token expires or is revoked, the user must re-authenticate:

Access Token Expired → Refresh Token Valid → New Access Token
Access Token Expired → Refresh Token Expired/Invalid → User Must Login Again

Security Best Practices

Access Tokens

• Never store access tokens in local storage for public clients (SPAs)
• Store in memory or secure, httpOnly cookies
• Validate expiration before each API call
• Include minimal claims to reduce token size

Refresh Tokens

• Store securely using httpOnly, secure cookies on the server
• Never expose to client-side JavaScript for public clients
• Implement refresh token rotation
• Set appropriate expiration times based on security requirements

Token Validation

Always validate tokens before trusting them:

// Example: Validate JWT structure (simplified)
function validateJWT(token) {
  try {
    const parts = token.split('.');
    if (parts.length !== 3) {
      throw new Error('Invalid JWT structure');
    }
    
    const header = JSON.parse(atob(parts[0]));
    const payload = JSON.parse(atob(parts[1]));
    
    if (Date.now() >= payload.exp * 1000) {
      throw new Error('Token expired');
    }
    
    return payload;
  } catch (error) {
    throw new Error('Token validation failed');
  }
}

Token Revocation

Guardhouse supports token revocation for security events:

• User logout - Revokes refresh tokens
• Password change - Invalidates all refresh tokens
• Account suspension - Revokes all tokens
• Manual revocation - Admin can revoke specific tokens

Use the revocation endpoint to invalidate tokens:

POST /oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=refresh_token_to_revoke
&token_type_hint=refresh_token
&client_id=your_client_id
&client_secret=your_client_secret

Common Token Errors

Error	Cause	Solution
invalid_token	Token expired or invalid	Refresh using refresh token or re-authenticate
invalid_grant	Refresh token expired or revoked	Require user to login again
invalid_client	Invalid client credentials	Verify client ID and secret
unauthorized_client	Client not authorized for grant type	Check client configuration

Token Storage Recommendations

Application Type	Access Token	Refresh Token
SPA (React/Vue)	In-memory	httpOnly cookie (via backend)
Web App (Server-rendered)	httpOnly cookie	httpOnly cookie
Mobile App	Secure storage (Keychain/Keystore)	Secure storage
Backend/M2M	Memory or cache	Secure storage

For detailed implementation guides, see the JavaScript/TypeScript or .NET sections.