Skip to main content

​
Overview

The Kin Conecta API uses session-based authentication to secure API endpoints. Authentication sessions are managed through the /api/auth_sessions endpoint.
The current implementation uses token hash authentication. Ensure you follow secure practices when generating and storing tokens.

​
Authentication Flow

The typical authentication flow involves:
  1. User logs in with credentials (handled by your authentication logic)
  2. Server creates an authentication session with a token
  3. Client includes the token in subsequent requests
  4. Server validates the token and session status
  5. Session expires or is revoked when user logs out

​
Auth Sessions

Authentication sessions track active user sessions and contain important security metadata.

​
Session Model

An authentication session includes:
FieldTypeDescription
sessionIdLongUnique session identifier
userIdLongID of the authenticated user
tokenHashStringHashed authentication token
expiresAtDateTimeToken expiration timestamp
revokedAtDateTimeRevocation timestamp (null if active)
ipStringIP address of the client
userAgentStringBrowser/client user agent
createdAtDateTimeSession creation timestamp

​
Creating a Session

Create a new authentication session when a user logs in.

​
Endpoint

POST /api/auth_sessions

​
Request Body

{
  "userId": 1,
  "tokenHash": "5f4dcc3b5aa765d61d8327deb882cf99",
  "expiresAt": "2026-03-12T10:30:00",
  "ip": "192.168.1.100",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "createdAt": "2026-03-11T10:30:00"
}

​
Example Request

curl -X POST "http://localhost:8080/api/auth_sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "tokenHash": "5f4dcc3b5aa765d61d8327deb882cf99",
    "expiresAt": "2026-03-12T10:30:00",
    "ip": "192.168.1.100",
    "userAgent": "Mozilla/5.0",
    "createdAt": "2026-03-11T10:30:00"
  }'

​
Response

{
  "sessionId": 42,
  "userId": 1,
  "tokenHash": "5f4dcc3b5aa765d61d8327deb882cf99",
  "expiresAt": "2026-03-12T10:30:00",
  "revokedAt": null,
  "ip": "192.168.1.100",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
  "createdAt": "2026-03-11T10:30:00"
}
Always hash tokens before storing them. Never store plain-text tokens in the database.

​
Retrieving Sessions

You can retrieve authentication sessions to verify active sessions or audit login activity.

​
Get All Sessions

curl -X GET "http://localhost:8080/api/auth_sessions"

​
Get Specific Session

curl -X GET "http://localhost:8080/api/auth_sessions/42"

​
Response

{
  "sessionId": 42,
  "userId": 1,
  "tokenHash": "5f4dcc3b5aa765d61d8327deb882cf99",
  "expiresAt": "2026-03-12T10:30:00",
  "revokedAt": null,
  "ip": "192.168.1.100",
  "userAgent": "Mozilla/5.0",
  "createdAt": "2026-03-11T10:30:00"
}

​
Updating a Session

Update a session to revoke it or modify its expiration.

​
Endpoint

PUT /api/auth_sessions/{sessionId}

​
Example: Revoking a Session

curl -X PUT "http://localhost:8080/api/auth_sessions/42" \
  -H "Content-Type: application/json" \
  -d '{
    "revokedAt": "2026-03-11T15:30:00"
  }'

​
Deleting a Session

Permanently delete a session from the database.

​
Endpoint

DELETE /api/auth_sessions/{sessionId}

​
Example Request

curl -X DELETE "http://localhost:8080/api/auth_sessions/42"

​
Response

204 No Content

​
Token Management Best Practices

Use cryptographically secure random number generators to create tokens. Minimum length should be 32 characters.
// Example in Node.js
const crypto = require('crypto');
const token = crypto.randomBytes(32).toString('hex');
Always hash tokens using a strong hashing algorithm (e.g., SHA-256) before storing in the database.
const crypto = require('crypto');
const tokenHash = crypto
  .createHash('sha256')
  .update(token)
  .digest('hex');
Sessions should expire after a reasonable time period:
  • Short-lived: 1-2 hours for high-security operations
  • Standard: 24 hours for regular user sessions
  • Long-lived: 7-30 days for “remember me” functionality
Always capture and store:
  • IP address for security auditing
  • User agent for device tracking
  • Creation timestamp for session history
Before processing requests, validate that:
  • Session exists and matches the user
  • Session has not expired (expiresAt > current time)
  • Session has not been revoked (revokedAt is null)
When users log out, update the session with a revokedAt timestamp rather than deleting it immediately. This maintains an audit trail.

​
Session Validation Example

Here’s a typical session validation flow: 
async function validateSession(sessionId, providedToken) {
  // 1. Fetch session from database
  const session = await fetch(`http://localhost:8080/api/auth_sessions/${sessionId}`);
  
  if (!session) {
    throw new Error('Session not found');
  }
  
  // 2. Check if revoked
  if (session.revokedAt) {
    throw new Error('Session has been revoked');
  }
  
  // 3. Check if expired
  if (new Date(session.expiresAt) < new Date()) {
    throw new Error('Session has expired');
  }
  
  // 4. Verify token hash
  const providedHash = hashToken(providedToken);
  if (providedHash !== session.tokenHash) {
    throw new Error('Invalid token');
  }
  
  // 5. Session is valid
  return session;
}
This is a simplified example. In production, implement additional security measures such as rate limiting, token rotation, and IP validation.

​
Common Authentication Errors

ErrorStatus CodeDescriptionSolution
Invalid token401Token hash doesn’t matchVerify token is correct and properly hashed
Session expired401Current time > expiresAtRequire user to log in again
Session revoked401revokedAt is not nullRequire user to log in again
Session not found404Session ID doesn’t existVerify session ID or create new session

​
Next Steps

User Management

Learn about user creation and management

Error Handling

Understand API error responses

Build docs developers (and LLMs) love

Get started for freeTalk to us