Authentication

Najeeb Health Suite uses the OAuth 2.0 Client Credentials flow for API authentication. This ensures secure, token-based access to all API endpoints.

Overview

The authentication process involves:

1. Obtaining Credentials: Get your Client ID and Client Secret from the Najeeb dashboard
2. Requesting Access Token: Exchange credentials for an access token
3. Using Access Token: Include the token in API requests via the Authorization header
4. Token Refresh: Tokens expire after 1 hour; request a new token when needed

Getting Your Credentials

After signing up for Najeeb Health Suite, you'll receive:

• Client ID: Your unique client identifier (e.g., client_abc123xyz)
• Client Secret: A secret key for authentication (e.g., secret_xyz789abc)

Keep Secrets Safe

Never expose your Client Secret in client-side code, public repositories, or logs. Store it securely in environment variables or a secrets management system.

Obtaining an Access Token

To authenticate, make a POST request to the token endpoint:

POST https://api.najeeb.com/v1/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=YOUR_CLIENT_ID&
client_secret=YOUR_CLIENT_SECRET

Example Request

cURL

curl -X POST https://api.najeeb.com/v1/auth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

JavaScript

const response = await fetch('https://api.najeeb.com/v1/auth/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: 'YOUR_CLIENT_ID',
    client_secret: 'YOUR_CLIENT_SECRET',
  }),
});

const data = await response.json();
const accessToken = data.access_token;

Python

import requests

response = requests.post(
    'https://api.najeeb.com/v1/auth/token',
    data={
        'grant_type': 'client_credentials',
        'client_id': 'YOUR_CLIENT_ID',
        'client_secret': 'YOUR_CLIENT_SECRET',
    },
    headers={'Content-Type': 'application/x-www-form-urlencoded'}
)

data = response.json()
access_token = data['access_token']

Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Using the Access Token

Include the access token in all API requests using the Authorization header:

GET https://api.najeeb.com/v1/patients
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Example

cURL

curl -X GET https://api.najeeb.com/v1/patients \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

JavaScript

const response = await fetch('https://api.najeeb.com/v1/patients', {
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
});

Python

headers = {
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json',
}
response = requests.get('https://api.najeeb.com/v1/patients', headers=headers)

Token Expiration

Access tokens expire after 1 hour (3600 seconds). You should:

1. Cache tokens: Store tokens with their expiration time
2. Refresh proactively: Request a new token before expiration
3. Handle 401 errors: If you receive a 401 Unauthorized, refresh your token and retry

Token Refresh Example

class NajeebClient {
  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.token = null;
    this.tokenExpiry = null;
  }

  async getToken() {
    // Check if token is still valid
    if (this.token && this.tokenExpiry > Date.now()) {
      return this.token;
    }

    // Request new token
    const response = await fetch('https://api.najeeb.com/v1/auth/token', {
      method: 'POST',
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams({
        grant_type: 'client_credentials',
        client_id: this.clientId,
        client_secret: this.clientSecret,
      }),
    });

    const data = await response.json();
    this.token = data.access_token;
    this.tokenExpiry = Date.now() + (data.expires_in * 1000) - 60000; // Refresh 1 min early
    
    return this.token;
  }

  async makeRequest(url, options = {}) {
    const token = await this.getToken();
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json',
      },
    });
  }
}

Error Responses

Invalid Credentials (401)

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

Missing Token (401)

{
  "error": "unauthorized",
  "error_description": "Missing or invalid access token"
}

Expired Token (401)

{
  "error": "invalid_token",
  "error_description": "The access token has expired"
}

Security Best Practices

Security Checklist

• ✅ Store credentials in environment variables
• ✅ Never commit secrets to version control
• ✅ Use HTTPS for all API requests
• ✅ Implement token caching and refresh logic
• ✅ Rotate credentials periodically
• ✅ Monitor for unauthorized access

Next Steps

• Quick Start Guide - Build your first API integration
• API Reference - Explore available endpoints