> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corebanq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication and Authorization

> Understanding the security model

CoreBanq implements a robust, multi-layered security model to ensure that only authorized users can access the API and perform actions on resources. This document outlines the authentication and authorization process.

## Authentication

Authentication in CoreBanq is handled using JSON Web Tokens (JWT). Here's the process:

1. A user submits their credentials - user id (usually email) and password to the `/authenticate` endpoint.
2. If the credentials are valid, the server generates a JWT token.
3. This token should be included in the `Authorization` header of subsequent requests as a Bearer token.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Server
    Client->>Server: POST /authenticate (credentials)
    Server->>Server: Validate credentials
    Server->>Client: Return JWT token
    Client->>Server: API request with JWT in Authorization header
    Server->>Server: Validate JWT
    Server->>Client: API response
```

<Note>The API is protected against brute-force attack - it sets an incremental cooling-off period for too many unsuccessful attempts.</Note>

## Authorization

Once authenticated, the system performs several checks to authorize each API request:

1. **Rate Limiting**: Checks if the request rate exceeds defined limits.
2. **API Access**: Verifies if the user (or their roles) has permission to call the specific API endpoint.
3. **Record Access**: For data operations, checks if the user has the appropriate CRUD permissions for the specific record.

### API Endpoint Registration

All API endpoints are registered in the database. This allows for centralized management of API access control.

### Record Type Registration

All record types (e.g., users, customers, accounts) are registered in the database. This facilitates fine-grained access control at the record level.

### Permission Checks

For each API call, the system performs the following checks in order:

1. **Rate Limiting**: Checks against general rules for public endpoints and specific rules stored in the database for private endpoints.
2. **Public Endpoint**: If it's a public endpoint (e.g., `/authenticate`), no further checks are needed.
3. **Token Validation**: For private endpoints, validates the Bearer token.
4. **API Access**: Checks if the user is granted access to execute this API.
5. **Record Access**: For data operations, verifies if the user is granted the specific action (Create, Read, Update, Delete) on the record. A special `CanReadAll` flag determines if record filtering should be applied.

```mermaid theme={null}
flowchart TD
    A[API Request] --> B{Rate Limit Check}
    B -->|Passed| C{Public Endpoint?}
    B -->|Failed| Z[Return 429 Too Many Requests]
    C -->|Yes| Y[Process Request]
    C -->|No| D{Validate JWT}
    D -->|Valid| E{Check API Access}
    D -->|Invalid| W[Return 401 Unauthorized]
    E -->|Granted| F{Check Record Access}
    E -->|Denied| X[Return 403 Forbidden]
    F -->|Granted| Y
    F -->|Denied| X
```

This multi-layered approach ensures that each request is thoroughly vetted before being processed, maintaining the security and integrity of the system.