Skip to main content

Authentication Concepts

This page provides a comprehensive understanding of how authentication works in Semaswift.

Token Types​

Access Tokens​

  • Purpose: Short-lived tokens for API access
  • Lifetime: 1 hour (configurable)
  • Format: JWT (RS256 signed)
  • Storage: Memory or secure cookie

Refresh Tokens​

  • Purpose: Obtain new access tokens
  • Lifetime: 30 days (configurable)
  • Format: Opaque token
  • Storage: Secure, HTTP-only cookie or secure storage

Personal Access Tokens (PAT)​

  • Purpose: Long-lived tokens for automation
  • Lifetime: User-defined (up to 1 year)
  • Format: pat_live_ prefix + random string
  • Storage: Hashed in database

JWT Structure​

Header.Payload.Signature
{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-123"
}

Payload​

{
  "sub": "usr_123456",
  "iss": "https://auth.semaswift.com",
  "aud": "semaswift-api",
  "exp": 1704067200,
  "iat": 1704063600,
  "nbf": 1704063600,
  "jti": "unique-token-id",
  "organization_id": "org_789",
  "roles": ["admin"],
  "permissions": ["user:*", "ticket:read"]
}

Permission Model​

Semaswift uses a hierarchical permission model:

organization
└── user
    └── role
        └── permissions

Permission Format​

resource:action

Examples:

  • user:read - Read user information
  • user:write - Create/update users
  • ticket:* - All ticket operations
  • *:* - Full access (super admin)

Role Hierarchy​

  1. Super Admin - Organization owner, all permissions
  2. Admin - User/role management, most operations
  3. Supervisor - Team management, reporting
  4. Agent - Basic operations, assigned queues/tickets
  5. Viewer - Read-only access

Session Management​

Login Flow​

sequenceDiagram
    participant Client
    participant API
    participant Auth Service
    participant Database

    Client->>API: POST /auth/login (email, password)
    API->>Auth Service: Validate credentials
    Auth Service->>Database: Check user, verify password
    Database-->>Auth Service: User data
    Auth Service->>Auth Service: Generate JWT
    Auth Service-->>API: Access + Refresh tokens
    API-->>Client: Tokens + User info

Token Refresh Flow​

sequenceDiagram
    participant Client
    participant API
    participant Auth Service

    Client->>API: POST /auth/refresh (refresh_token)
    API->>Auth Service: Validate refresh token
    Auth Service->>Auth Service: Check expiry, not revoked
    Auth Service->>Auth Service: Generate new access token
    Auth Service-->>API: New access token
    API-->>Client: New access token

Security Features​

Token Blacklisting​

Revoked tokens are blacklisted until expiration:

POST /api/v1/auth/logout
Authorization: Bearer YOUR_TOKEN

Concurrent Session Limits​

Organizations can configure maximum concurrent sessions per user.

IP Allowlisting​

Restrict API access to specific IP ranges:

{
  "allowed_ips": ["192.168.1.0/24", "10.0.0.1"]
}

Audit Logging​

All authentication events are logged:

  • Login attempts (success/failure)
  • Token refresh
  • Logout
  • Password changes
  • MFA enrollment/verification

OAuth2/OIDC Details​

Supported Flows​

FlowUse Case
Authorization CodeWeb apps with backend
Authorization Code + PKCEMobile/SPA apps
Client CredentialsServer-to-server

Endpoints​

EndpointURL
Authorizationhttps://auth.semaswift.com/oauth2/auth
Tokenhttps://auth.semaswift.com/oauth2/token
UserInfohttps://auth.semaswift.com/userinfo
JWKShttps://auth.semaswift.com/.well-known/jwks.json
Discoveryhttps://auth.semaswift.com/.well-known/openid-configuration

Best Practices​

  1. Store refresh tokens securely - Use HTTP-only cookies or secure storage
  2. Implement token rotation - Rotate refresh tokens on use
  3. Handle token expiry gracefully - Implement automatic refresh
  4. Use appropriate token lifetimes - Balance security and UX
  5. Implement logout everywhere - Revoke all sessions when needed