Authentication

Authentication is a fundamental security mechanism of the CleverCards API, designed to ensure that only authorized users and systems can access protected resources and perform sensitive operations.

All API requests must be authenticated using a combination of:

• API Key (X-API-Key): A static key issued to each client or integration partner, identifying the source of the request. This key must be included in the request headers and is used to validate the caller’s access rights.

• Token (Authorization header): A short-lived access token obtained by performing a login request using valid user credentials. This token must accompany all subsequent API calls to verify the identity and session context of the user.

To initiate an authenticated session, clients must first call the /login endpoint, providing a valid username and password. Upon successful authentication, the API responds with a bearer token, which is then used in the Authorization header of future requests.

Authentication Flow Overview:

1. Login

   • POST /login
   • Authenticate using username, password, and API key.
   • Receive a bearer token upon success.

2. Authorized Requests

   • Include the following headers in all API calls:

     Authorization: <access_token>
     X-API-Key: <your_api_key>
     CompanyAccountId: <your_company_account_id>

The CleverCards Platform uses AWS Cognito as the underlying identity provider to ensure scalable, secure, and standards-based user authentication. All sessions are time-bound and access tokens are subject to expiration, requiring periodic re-authentication.

This dual-layer authentication model (API Key + Bearer Token) provides strong security guarantees while supporting granular access control and auditability across company accounts and users.