Skip to main content

​
Overview

The DonaSF API uses JSON Web Tokens (JWT) for secure authentication. After successfully logging in, you’ll receive a JWT token that must be included in subsequent API requests to access protected endpoints.

​
Authentication Flow

  1. Submit credentials to the login endpoint
  2. Receive a JWT token in the response
  3. Include the token in the Authorization header for authenticated requests
  4. Token expires after 7 days

​
Obtaining a JWT Token

​
Login Endpoint

curl -X POST https://api.donasf.com/Cliente/Login \
  -H "Content-Type: application/json" \
  -d '{
    "Identificador": "[email protected]",
    "Password": "your_password"
  }'

​
Request Parameters

​
Identificador
string
required
User identifier - can be either email address or phone number
​
Password
string
required
User password

​
Response Fields

​
Tokens
string
The JWT token string to use for authenticated requests
​
Identificador
string
The user’s identifier (email or phone)
​
Expiracion
datetime
Token expiration timestamp (UTC)
​
IdCliente
integer
Unique client/user identifier
​
Nombre
string
User’s display name
​
Activo
boolean
Account active status

​
Response Example

{
  "Tokens": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJJZENsaWVudGUiOiIxMjMiLCJJZGVudGlmaWNhZG9yIjoidXNlckBleGFtcGxlLmNvbSIsImNvcnJlbyI6InVzZXJAZXhhbXBsZS5jb20iLCJ0ZWxlZm9ubyI6IisxMjM0NTY3ODkwIiwibm9tYnJlIjoiSm9obiBEb2UiLCJDb250cmFzZW5hIjoiaGFzaGVkX3Bhc3N3b3JkIiwiZXhwIjoxNzEwNTA0MDAwfQ.signature",
  "Identificador": "[email protected]",
  "Expiracion": "2026-03-13T10:30:00Z",
  "IdCliente": 123,
  "Nombre": "John Doe",
  "Activo": true
}

​
Alternative Login: Identity Provider

For users authenticating via external identity providers (Google, Facebook, etc.): 
curl -X POST https://api.donasf.com/Cliente/LoginID \
  -H "Content-Type: application/json" \
  -d '{
    "IdProvider": "google_user_id_12345",
    "Identificador": "[email protected]"
  }'

​
Token Structure

The JWT token contains the following claims:
ClaimDescriptionSource
IdClienteUnique client IDDatabase
IdentificadorUser identifier (email/phone)Login request
correoUser’s email addressDatabase
telefonoUser’s phone numberDatabase
nombreUser’s full nameDatabase
ContrasenaPassword hash (standard login only)Login request
IdProviderIdentity provider ID (OAuth login only)Login request
expToken expiration timestampGenerated
The token expires 7 days after issuance. You’ll need to re-authenticate when the token expires.

​
Token Validation Parameters

The API validates JWT tokens using the following parameters (configured in Program.cs:22-29):
ParameterValueDescription
ValidateIssuerfalseIssuer validation is disabled
ValidateAudiencefalseAudience validation is disabled
ValidateLifetimetrueToken expiration is checked
ValidateIssuerSigningKeytrueSignature verification is required
IssuerSigningKeyFrom appsettings.json256-bit symmetric key
The signing key is stored in appsettings.json under Jwt:Key. In production, this should be stored securely using environment variables or a secrets manager.

​
Using the Token in Requests

Include the JWT token in the Authorization header with the Bearer scheme: 
curl -X GET https://api.donasf.com/protected-endpoint \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Token Expiration

  • Standard Login: Tokens expire 7 days after issuance
  • Configured in: ClienteController.cs:128 and ClienteController.cs:166
  • Expiration Format: UTC datetime in ISO 8601 format
  • Configuration Setting: appsettings.json contains Jwt:Expires: 3600 (in seconds, equals 1 hour) but the actual implementation uses 7 days
There’s a discrepancy between the configuration file (1 hour) and the actual implementation (7 days). The code implementation takes precedence.

​
Error Responses

​
Invalid Credentials

{
  "error": "Usuario o contraseña incorrectos"
}
HTTP Status: 400 Bad Request

​
Missing Parameters

{
  "error": "Error: [specific error message]"
}
HTTP Status: 400 Bad Request

​
Server Error

{
  "error": "Error al realizar el login: [exception message]"
}
HTTP Status: 400 Bad Request

​
Security Best Practices

Important Security Considerations:
  • Always use HTTPS in production
  • Store tokens securely (never in localStorage for sensitive apps)
  • Implement token refresh mechanism before expiration
  • Don’t expose tokens in URLs or logs
  • Rotate signing keys regularly in production
  1. Token Storage: Store tokens in secure, httpOnly cookies or secure storage mechanisms
  2. Token Transmission: Always use HTTPS to prevent token interception
  3. Token Expiration: Monitor token expiration and implement refresh logic
  4. Signing Key: Use strong, randomly generated keys (minimum 256 bits)
  5. Environment-Specific Keys: Use different signing keys for development, staging, and production

​
Implementation Details

​
JWT Configuration Location

  • Configuration: Program.cs:19-30
  • Token Generation: ClienteController.cs:110-146 (standard login)
  • Token Generation (OAuth): ClienteController.cs:149-185 (identity provider)
  • Settings: appsettings.json:9-12

​
Algorithm

  • Signing Algorithm: HMAC-SHA256 (HS256)
  • Key Type: Symmetric (shared secret)
  • Key Source: Configuration file (appsettings.json)

​
Next Steps

Donations API

Explore donation management endpoints

Architecture

Learn about the system architecture

Build docs developers (and LLMs) love

Get started for freeTalk to us