GET /auth/authorize?
  response_type=code&
  client_id=client_abc123&
  redirect_uri=https://yourapp.com/callback&
  scope=openid%20profile%20email&
  state=random_state_string&
  code_challenge=CHALLENGE_STRING&
  code_challenge_method=S256

{
  "grant_type": "authorization_code",
  "code": "AUTHORIZATION_CODE",
  "client_id": "client_abc123",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "https://yourapp.com/callback",
  "code_verifier": "PKCE_VERIFIER"
}

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_abc123...",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "openid profile email"
}

{
  "error": "invalid_grant",
  "error_description": "Authorization code expired"
}

{
  "sub": "user-unique-id",
  "email": "[email protected]",
  "email_verified": true,
  "name": "John Doe",
  "firstName": "John",
  "lastName": "Doe",
  "workerProfileId": "worker-123",
  "userIds": [
    {
      "id": "user-789",
      "clientId": "client-xyz"
    }
  ]
}

{
  "error": "invalid_token",
  "error_description": "Access token expired"
}

{
  "grant_type": "refresh_token",
  "refresh_token": "YOUR_REFRESH_TOKEN",
  "client_id": "client_abc123",
  "client_secret": "YOUR_CLIENT_SECRET"
}

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_new123...",
  "scope": "openid profile email"
}

// JavaScript example
const codeVerifier = base64URLEncode(crypto.randomBytes(32));
// Example: "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

const codeChallenge = base64URLEncode(
  crypto.createHash('sha256').update(codeVerifier).digest()
);

GET /auth/authorize?
  ...
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256

{
  "grant_type": "authorization_code",
  ...
  "code_verifier": "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
}

{
  "iss": "https://api.dashboard.listoglobal.com",
  "sub": "user-unique-id",
  "aud": "client_abc123",
  "exp": 1701238167,
  "iat": 1701234567,
  "nonce": "your-nonce-value",
  "client_id": "client_abc123",
  "scope": "openid profile email"
}

// 1. Generate PKCE values
const codeVerifier = generateRandomString(43);
const codeChallenge = base64URLEncode(sha256(codeVerifier));

// 2. Store state and code_verifier in session
const state = generateRandomString(32);
session.store('oauth_state', state);
session.store('code_verifier', codeVerifier);

// 3. Redirect user to authorization endpoint
const authUrl = 'https://api.dashboard.listoglobal.com/auth/authorize?' +
  'response_type=code&' +
  'client_id=client_abc123&' +
  'redirect_uri=https://yourapp.com/callback&' +
  'scope=openid%20profile%20email&' +
  'state=' + state;

redirect(authUrl);

// 4. Handle callback
app.get('/callback', async (req, res) => {
  const { code, state } = req.query;
  
  // Verify state
  if (state !== session.get('oauth_state')) {
    throw new Error('Invalid state - possible CSRF attack');
  }
  
  // Exchange code for tokens
  const tokenResponse = await fetch('https://api.dashboard.listoglobal.com/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'authorization_code',
      code: code,
      client_id: 'client_abc123',
      client_secret: 'YOUR_CLIENT_SECRET',
      redirect_uri: 'https://yourapp.com/callback',
      code_verifier: session.get('code_verifier')
    })
  });
  
  const tokens = await tokenResponse.json();
  
  // Store tokens securely
  session.store('access_token', tokens.access_token);
  session.store('refresh_token', tokens.refresh_token);
  
  // Decode the tokens.id_token and get the email, and user claims
  // OR
  // Fetch user info
  const userInfoResponse = await fetch('https://api.dashboard.listoglobal.com/auth/userinfo', {
    headers: {
      'Authorization': 'Bearer ' + tokens.access_token
    }
  });
  
  const userInfo = await userInfoResponse.json();
  
  // User is now authenticated!
  console.log('User:', userInfo);
});

// 5. Refresh token when needed
async function refreshAccessToken() {
  const refreshToken = session.get('refresh_token');
  
  const response = await fetch('https://api.dashboard.listoglobal.com/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      grant_type: 'refresh_token',
      refresh_token: refreshToken,
      client_id: 'client_abc123',
      client_secret: 'YOUR_CLIENT_SECRET'
    })
  });
  
  const tokens = await response.json();
  session.store('access_token', tokens.access_token);
  session.store('refresh_token', tokens.refresh_token);
}

---

## Security Best Practices

### ✅ Do's

1. **Use HTTPS** for all requests in production
2. **Validate the `state` parameter** in callbacks to prevent CSRF attacks
3. **Implement PKCE** for public clients (SPAs, mobile apps)
4. **Store tokens securely**:
   - Backend: Encrypted session storage or httpOnly cookies
   - Mobile: Secure keychain/keystore
   - Never store in localStorage for web apps
5. **Validate ID tokens** before trusting the claims
6. **Refresh tokens proactively** before they expire
7. **Revoke tokens** when user logs out
8. **Use short-lived access tokens** (default: 1 hour)
9. **Handle token expiration** gracefully with refresh tokens

### ❌ Don'ts

1. **Never expose `client_secret`** in public clients (JavaScript, mobile apps)
2. **Never share tokens** between users or sessions
3. **Never log tokens** in plain text
4. **Don't skip `state` validation** - critical for security
5. **Don't store tokens** in localStorage (web) - use httpOnly cookies
6. **Don't ignore token expiration** - handle gracefully

---

## Client Types

### Confidential Clients (Server-Side Applications)

**Examples**: Traditional web apps with backend servers

**Characteristics**:
- Can securely store `client_secret`
- Required to authenticate with `client_secret` on token requests
- PKCE is optional but recommended

### Public Clients (Client-Side Applications)

**Examples**: Single Page Apps (SPAs), mobile apps, desktop apps

**Characteristics**:
- Cannot securely store `client_secret`
- Must use PKCE for security
- Token requests don't require `client_secret`

---

## Token Lifetimes

| Token Type | Default Lifetime | Renewable |
|-----------|------------------|-----------|
| Authorization Code | 10 minutes | No (single-use) |
| Access Token | 1 hour | Via refresh token |
| Refresh Token | 30 days | Yes (rolling) |
| ID Token | 1 hour | Via refresh token |

**Note**: Your client may have custom token lifetimes. Check with your administrator.

---

## Support

For integration support or to register your application, contact your system administrator or account manager.

## Standards & Compliance

This OAuth 2.0/OIDC implementation follows these standards:

- [OAuth 2.0 (RFC 6749)](https://tools.ietf.org/html/rfc6749)
- [OAuth 2.0 PKCE (RFC 7636)](https://tools.ietf.org/html/rfc7636)
- [OpenID Connect Core 1.0](https://openid.net/specs/openid-connect-core-1_0.html)
- [JSON Web Token (JWT) (RFC 7519)](https://tools.ietf.org/html/rfc7519)

---

*Last updated: December 2025*