Session Management

Users can view, manage, and revoke their active sessions and personal API tokens. Organization admins can also manage sessions for their members.

Sessions

Managed by the SessionController. Each session corresponds to a Sanctum personal access token with associated metadata.

List Active Sessions

GET /api/auth/sessions

Returns all active sessions for the authenticated user, including the current session.

{
    "sessions": [
        {
            "id": 1,
            "name": "web-session",
            "ip_address": "192.168.1.100",
            "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
            "last_used_at": "2026-03-21T10:30:00Z",
            "created_at": "2026-03-20T08:00:00Z",
            "is_current": true
        },
        {
            "id": 2,
            "name": "web-session",
            "ip_address": "10.0.0.50",
            "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)...",
            "last_used_at": "2026-03-19T14:22:00Z",
            "created_at": "2026-03-18T09:15:00Z",
            "is_current": false
        }
    ]
}

Revoke a Session

DELETE /api/auth/sessions/{tokenId}

Revokes a specific session by its token ID. The user cannot revoke their current session — use the logout endpoint instead.

{
    "message": "Session revoked."
}

Revoke All Sessions

DELETE /api/auth/sessions

Revokes all sessions except the current one. Useful when a user suspects unauthorized access to their account.

{
    "message": "All other sessions have been revoked."
}

Personal API Tokens

Managed by the PersonalTokenController. Users can create long-lived API tokens for programmatic access to their account.

List Tokens

GET /api/user/tokens

Returns all personal API tokens for the authenticated user.

{
    "tokens": [
        {
            "id": 5,
            "name": "CI/CD Pipeline",
            "abilities": ["read", "write"],
            "last_used_at": "2026-03-21T09:00:00Z",
            "created_at": "2026-01-15T12:00:00Z"
        }
    ]
}

Create Token

POST /api/user/tokens

{
    "name": "CI/CD Pipeline",
    "abilities": ["read", "write"]
}

Returns the plain-text token value. This is the only time the token is shown — it is hashed before storage and cannot be retrieved later.

{
    "token": "5|abc123def456...",
    "name": "CI/CD Pipeline",
    "abilities": ["read", "write"]
}

Delete Token

DELETE /api/user/tokens/{token}

Permanently deletes a personal API token. Any requests using this token will immediately fail with 401 Unauthorized.

{
    "message": "Token deleted."
}

IP Address & User Agent Tracking

When a token is created (either via login or the personal token endpoint), the user's IP address and user agent string are recorded. This metadata is displayed in the session management UI so users can identify which devices are logged in.

• IP address — captured from the request at token creation time
• User agent — captured from the User-Agent header at token creation time
• This data is stored on the Sanctum personal_access_tokens table in custom ip_address and user_agent columns

Organization Session Management

Organization admins can view and revoke sessions for members of their organization via the OrgSessionController.

List Member Sessions

GET /api/organizations/{org}/members/{user}/sessions

Returns all active sessions for a specific organization member. Requires the admin or owner role within the organization.

Revoke Member Session

DELETE /api/organizations/{org}/members/{user}/sessions/{tokenId}

Revokes a specific session for an organization member. The affected user is immediately logged out of that session.

Revoke All Member Sessions

DELETE /api/organizations/{org}/members/{user}/sessions

Revokes all sessions for an organization member, forcing them to re-authenticate on all devices.

MFA Challenge Tokens

When a user with MFA enabled logs in, a short-lived challenge token is issued instead of a full session token. These tokens:

• Expire after 10 minutes
• Can only be used with the POST /api/auth/mfa/verify endpoint
• Cannot access any other API endpoints
• Are automatically cleaned up after expiry
• Are scoped with a single mfa-challenge ability to prevent misuse