Authentication

Learn how to authenticate with the Fayda Authentication API.

API Key Authentication

All requests to the Fayda Authentication API must include an API key for authentication. You can obtain an API key from your developer dashboard.

Authentication Methods

You can authenticate your API requests in one of two ways:

1. Authorization Header (Recommended)

Include your API key in the Authorization header using the Bearer scheme:

json

Authorization: Bearer YOUR_API_KEY

2. X-API-Key Header

Include your API key in the X-API-Key header:

text

X-API-Key: YOUR_API_KEY

Important

Keep your API key secure. Never share it or include it in client-side code. Use environment variables or secure secret management systems to store your API key.

Example Request

bash

curl -X POST https://fayda-auth.vercel.app/api/fayda/otp/initiate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fcn": "1234567890123456"}'

API Key Management

Manage your API keys from the developer dashboard.

Generating API Keys

To generate a new API key:

Log in to your developer dashboard
Navigate to the "API Keys" section
Click "Generate New Key"
Provide a name for your key (e.g., "Production")
Select the appropriate permissions for the key
Click "Create"

Your API key will be displayed only once. Make sure to copy it and store it securely.

API Key Permissions

API keys can have different permission levels:

Permission	Description	Recommended For
Read-Only	Can only access read-only endpoints (e.g., GET requests).	Monitoring and analytics.
Standard	Can access all standard API endpoints for user authentication.	Most applications.
Admin	Full access, including administrative functions like updating configuration.	Administrative tools only.

Revoking API Keys

To revoke an API key:

Log in to your developer dashboard
Navigate to the "API Keys" section
Find the key you want to revoke and click "Revoke"
Confirm the action

Once revoked, a key cannot be reinstated.

Best Practice

Rotate your API keys regularly for enhanced security. When rotating keys, generate a new key, update your applications to use it, then revoke the old key once you've confirmed everything is working.

API Environments

Use the sandbox for testing and production for live applications.

Sandbox Environment

For development and testing. Uses mock data.

Base URL:

text

https://fayda-auth.vercel.app

Test Credentials:

FCN: 1234567890123456
OTP: 123456 (always works)

Production Environment

Connects to the real Fayda system for live applications.

Base URL:

text

https://fayda-auth.vercel.app

Important

Always use separate API keys for sandbox and production environments. Never use production API keys in development or testing.

User Authentication Flow

The API uses a two-step OTP flow to authenticate users.

Overview

Initiate OTP
Send the user's FCN to request an OTP to be sent to their registered mobile number.
Verify OTP
Send the OTP entered by the user, along with the transaction ID and FCN, to verify their identity.

Authentication Flow Diagram

text

sequenceDiagram
    participant App as Your Application
    participant API as Fayda API
    participant SMS as SMS Gateway
    participant User as End User
    
    App->>API: 1. Initiate OTP (FCN)
    API->>SMS: 2. Send OTP to user's phone
    SMS->>User: 3. Deliver OTP via SMS
    User->>App: 4. Enter OTP
    App->>API: 5. Verify OTP (transactionId, OTP, FCN)
    API->>App: 6. Return user data if verified

Step 1: Initiate OTP

Send a request to initiate the OTP verification process.

Endpoint:

text

POST /api/fayda/otp/initiate

Request Body:

text

{
  "fcn": "1234567890123456"
}

Successful Response (200 OK):

json

{
  "success": true,
  "transactionId": "cd8e1472-57f4-49a2-ace9-6ec24ad3ac52",
  "maskedMobile": "09xxxxxx24",
  "status": "SUCCESS",
  "message": "OTP sent",
  "statusCode": 200
}

View detailed OTP initiation docs

Step 2: Verify OTP

After the user enters the OTP, send a verification request.

Endpoint:

text

POST /api/fayda/otp/verify

Request Body:

json

{
  "transactionId": "cd8e1472-57f4-49a2-ace9-6ec24ad3ac52",
  "otp": "123456",
  "fcn": "1234567890123456"
}

Successful Response (200 OK):

json

{
  "success": true,
  "transactionId": "cd8e1472-57f4-49a2-ace9-6ec24ad3ac52",
  "user": {
    "uin": "8957253029940",
    "fullName": "John Doe",
    // ... other user details
  },
  "photo": "base64-encoded-image-data",
  "qrCode": "base64-encoded-qr-data"
}

View detailed OTP verification docs

Security Best Practices

Follow these best practices to ensure the security of your application and user data.

API Key Security

Store API keys securely using environment variables or a secrets management system.
Never expose API keys in client-side code or public repositories.
Rotate API keys regularly (e.g., every 90 days).
Use different API keys for different environments (development, production).
Apply the principle of least privilege when assigning permissions.

User Data Security

Always use HTTPS for all API communications.
Encrypt sensitive user data at rest.
Implement proper access controls for user data.
Only store the minimum user data required.
Implement a clear data retention policy.

Implementation Best Practices

Implement server-side validation for all inputs.
Use a server-side proxy for API calls, not from client-side code.
Implement proper error handling and logging.
Set appropriate timeouts for API requests.
Implement rate limiting to prevent abuse.