Internal Endpoints

Moka.Auth provides a set of built-in endpoints that can be enabled or disabled based on your needs. These endpoints provide ready-to-use functionality for authentication, user management, role management, and more.

Enabling Internal Endpoints

You can enable all or specific endpoints using MapMokaDefaultEndpoints:

app.MapMokaDefaultEndpoints(options =>
{
    options.EnableAuthEndpoints = true;
    options.EnableUserEndpoints = true;
    options.EnableRoleEndpoints = true;
    options.EnablePermissionEndpoints = true;
    options.EnableApiKeyEndpoints = true;
    options.EnableImpersonationEndpoints = true;
});

Authentication Endpoints

Base path: /auth

Endpoint	Method	Description	Request Body	Response
`/auth/login`	POST	Authenticate user	`{ "username": "string", "password": "string" }`	`{ "token": "string" }`
`/auth/refresh`	POST	Refresh JWT token	`{ "refreshToken": "string" }`	`{ "token": "string", "refreshToken": "string" }`
`/auth/validate`	POST	Validate token	`{ "token": "string" }`	`{ "isValid": true }`

Example Requests

POST /auth/login
Content-Type: application/json

{
    "username": "john.doe",
    "password": "SecurePass123!"
}

Success Response

{
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "abc123...",
    "expiresAt": "2024-03-09T20:13:13Z",
    "user": {
        "id": "123",
        "username": "john.doe",
        "email": "[email protected]",
        "roles": ["User"],
        "permissions": ["read:data"]
    }
}

Error Response

{
    "error": "InvalidCredentials",
    "message": "Invalid username or password",
    "details": {
        "remainingAttempts": 4,
        "lockoutMinutes": 30
    }
}

User Management Endpoints

Base path: /users

Endpoint	Method	Description	Request Body	Response
`/users`	GET	List all users	-	Array of users
`/users/{id}`	GET	Get user by ID	-	User details
`/users`	POST	Create user	User object	Created user
`/users/{id}`	PUT	Update user	User object	Updated user
`/users/{id}`	DELETE	Delete user	-	204 No Content
`/users/{id}/roles`	GET	Get user roles	-	Array of roles
`/users/{id}/permissions`	GET	Get user permissions	-	Array of permissions

Example Requests

Create User

POST /users
Content-Type: application/json

{
    "username": "jane.smith",
    "email": "[email protected]",
    "password": "SecurePass123!",
    "firstName": "Jane",
    "lastName": "Smith",
    "roles": ["User"],
    "permissions": ["read:data"]
}

Success Response

{
    "id": "456",
    "username": "jane.smith",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "Smith",
    "roles": ["User"],
    "permissions": ["read:data"],
    "createdAt": "2024-03-09T16:13:13Z"
}

Error Response

{
    "error": "ValidationError",
    "message": "Invalid user data",
    "details": {
        "email": ["Invalid email format"],
        "password": ["Password must be at least 8 characters"]
    }
}

Role Management Endpoints

Base path: /roles

Endpoint	Method	Description	Request Body	Response
`/roles`	GET	List all roles	-	Array of roles
`/roles/{id}`	GET	Get role by ID	-	Role details
`/roles`	POST	Create role	Role object	Created role
`/roles/{id}`	PUT	Update role	Role object	Updated role
`/roles/{id}`	DELETE	Delete role	-	204 No Content
`/roles/{id}/permissions`	GET	Get role permissions	-	Array of permissions
`/roles/{id}/users`	GET	Get users in role	-	Array of users

Example Requests

Create Role

POST /roles
Content-Type: application/json

{
    "name": "Editor",
    "description": "Content editor role",
    "permissions": ["content:read", "content:write"]
}

Success Response

{
    "id": 789,
    "name": "Editor",
    "description": "Content editor role",
    "permissions": ["content:read", "content:write"],
    "createdAt": "2024-03-09T16:13:13Z"
}

Permission Management Endpoints

Base path: /permissions

Endpoint	Method	Description	Request Body	Response
`/permissions`	GET	List all permissions	-	Array of permissions
`/permissions/{id}`	GET	Get permission by ID	-	Permission details
`/permissions`	POST	Create permission	Permission object	Created permission
`/permissions/{id}`	PUT	Update permission	Permission object	Updated permission
`/permissions/{id}`	DELETE	Delete permission	-	204 No Content

Example Requests

Create Permission

POST /permissions
Content-Type: application/json

{
    "name": "content:write",
    "description": "Can write content",
    "category": "Content"
}

Success Response

{
    "id": 101,
    "name": "content:write",
    "description": "Can write content",
    "category": "Content",
    "createdAt": "2024-03-09T16:13:13Z"
}

API Key Management Endpoints

Base path: /apikeys

Endpoint	Method	Description	Request Body	Response
`/apikeys`	GET	List all API keys	-	Array of API keys
`/apikeys/{id}`	GET	Get API key by ID	-	API key details
`/apikeys`	POST	Create API key	API key object	Created API key
`/apikeys/{id}`	PUT	Update API key	API key object	Updated API key
`/apikeys/{id}`	DELETE	Delete API key	-	204 No Content

Example Requests

Create API Key

POST /apikeys
Content-Type: application/json

{
    "name": "Service Integration",
    "description": "Key for service integration",
    "expiresAt": "2025-03-09T16:13:13Z",
    "permissions": ["api:read", "api:write"]
}

Success Response

{
    "id": 202,
    "name": "Service Integration",
    "key": "mka_abc123...", // Only shown once at creation
    "description": "Key for service integration",
    "expiresAt": "2025-03-09T16:13:13Z",
    "permissions": ["api:read", "api:write"],
    "createdAt": "2024-03-09T16:13:13Z"
}

Error Handling

All endpoints follow a consistent error response format:

{
    "error": "ErrorType",
    "message": "Human readable error message",
    "details": {
        // Additional error context
    },
    "traceId": "request-trace-id"
}

Common error types:

ValidationError: Invalid request data
NotFound: Resource not found
Unauthorized: Missing or invalid authentication
Forbidden: Insufficient permissions
Conflict: Resource conflict
RateLimitExceeded: Too many requests

Security Considerations

Endpoint Protection
- All management endpoints require authentication
- Role-based access control enforced
- Rate limiting applied to prevent abuse
Role-Based Access Default permissions required:
- User endpoints: “Users:Manage”
- Role endpoints: “Roles:Manage”
- Permission endpoints: “Permissions:Manage”
- API key endpoints: “ApiKeys:Manage”
Rate Limiting Default limits per IP:
- Authentication endpoints: 5 requests/minute
- Management endpoints: 60 requests/minute
- Read operations: 100 requests/minute
Selective Enabling Only enable required endpoints:

app.MapMokaDefaultEndpoints(options =>
{
    options.EnableAuthEndpoints = true;     // Enable only auth endpoints
    options.EnableUserEndpoints = false;    // Disable all others
    options.EnableRoleEndpoints = false;
    options.EnablePermissionEndpoints = false;
    options.EnableApiKeyEndpoints = false;
});

Security Headers All endpoints include:
- X-Content-Type-Options: nosniff
- X-Frame-Options: DENY
- X-XSS-Protection: 1; mode=block
- Strict-Transport-Security: max-age=31536000
Input Validation
- All inputs strictly validated
- SQL injection protection
- XSS protection
- Request size limits enforced

Internal Endpoints

Enabling Internal Endpoints

Authentication Endpoints

Example Requests

Login Request

Success Response

Error Response

User Management Endpoints

Example Requests

Create User

Success Response

Error Response

Role Management Endpoints

Example Requests

Create Role

Success Response

Permission Management Endpoints

Example Requests

Create Permission

Success Response

API Key Management Endpoints

Example Requests

Create API Key

Success Response

Error Handling

Security Considerations