Authentication

B2B integrations authenticate using an API token generated from the Crinsutrack web app. Tokens are created by an administrator or by the developer setting up the integration.

OAuth 2.0 Client Credentials flow is also supported as an authentication option for server-to-server integrations.

Full OAuth 2.0 setup documentation is coming soon. Contact your Crinsutrack administrator for details.

Generate an API token

See API Tokens for the full steps on generating, copying, and revoking tokens from the web app.

Make API requests

Include the token in the Authorization header of every request:

curl https://your-api-host/api/v1/external/subjects \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Python client example

import requests

class CrinsutrackClient:
    def __init__(self, api_token: str):
        self.base_url = "https://your-api-host"
        self.headers = {"Authorization": f"Bearer {api_token}"}

    def request(self, method, endpoint, **kwargs):
        headers = {**self.headers, **kwargs.pop("headers", {})}
        response = requests.request(method, f"{self.base_url}{endpoint}", headers=headers, **kwargs)
        response.raise_for_status()
        return response

client = CrinsutrackClient(api_token="your-api-token")

# Create a procedure
procedure = client.request("POST", "/api/v1/external/procedures", json={
    "type": "STORE",
    "facilityId": 1,
    "subjectCode": "SUBJ-2024-001",
    "sampleContainers": [
        {"name": "VL-001", "description": "Vial 1"}
    ]
}).json()

# Check procedure status
status = client.request("GET", f"/api/v1/external/procedures/{procedure['id']}").json()

---

Security best practices

1. Copy the token at creation time - it will not be shown again. See API Tokens for details.
2. Never expose tokens in frontend code, mobile apps, or public repositories
3. Store tokens securely using environment variables or a secrets manager
4. Use separate tokens for development, staging, and production environments
5. Rotate tokens regularly - revoke the old one and generate a new one from API Tokens
6. Monitor API usage - review access logs for unexpected activity

---

Revoking a token

To revoke a token, follow the steps in API Tokens. All subsequent requests using the revoked token will be rejected immediately.

---

Troubleshooting

Error	Cause	Solution
401 Unauthorized	Missing, invalid, or revoked token	Verify the token value; generate a new one from API Tokens if lost
403 Forbidden	Operation not permitted for B2B integrations	See Roles & Permissions
429 Too Many Requests	Rate limit exceeded	Wait and retry with exponential backoff