API Authentication

2026-02-01 · 4 min

Overview

The Bio Ecko API uses OAuth 2.0 Bearer tokens for authentication. All API requests must include a valid access token in the Authorization header. Tokens are scoped to specific permissions matching the API user's role.

Obtaining Credentials

To use the API, you need client credentials:

1. Navigate to Admin > Settings > API Access.
2. Click Create API Client.
3. Enter a client name and description (e.g., 'Lab Interface', 'Mobile App').
4. Select the API scopes (permissions) this client needs.
5. The system generates a Client ID and Client Secret.
6. Store the Client Secret securely -- it's shown only once.

Each API client has its own credentials and audit trail.

Token Exchange

Exchange credentials for an access token:

POST /api/v1/auth/token Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials &client_id=YOUR_CLIENT_ID &client_secret=YOUR_CLIENT_SECRET

Response: { "access_token": "eyJhbGciOiJSUz...", "token_type": "Bearer", "expires_in": 3600, "scope": "patients:read appointments:write" }

Tokens expire after 1 hour (configurable). Request a new token when expired.

Using the Token

Include the token in every API request:

GET /api/v1/patients Authorization: Bearer eyJhbGciOiJSUz... Content-Type: application/json

If the token is expired or invalid, the API returns 401 Unauthorized.

Scopes

API scopes control what the client can access:

• patients:read / patients:write -- Patient demographics.
• appointments:read / appointments:write -- Appointment scheduling.
• billing:read / billing:write -- Invoice and payment data.
• lab:read / lab:write -- Lab orders and results.
• pharmacy:read / pharmacy:write -- Dispensing and stock.
• emr:read -- Clinical records (read-only for integration partners).

Assign the minimum scopes needed for the integration's purpose.

Security Best Practices

• Store Client Secrets in environment variables, never in code.
• Use HTTPS for all API calls.
• Rotate Client Secrets periodically.
• Monitor API usage in the audit log.
• Revoke credentials immediately if compromised.
• Use IP whitelisting for production API clients.
• Set rate limits per client to prevent abuse.

Notes

Related topics