Skip to main content

​
Authentication Methods

AllCare supports two authentication methods:

API Keys

Simple authentication for server-to-server integrations

OAuth 2.0

Standard OAuth flow for user-delegated access

​
API Key Authentication

​
Obtaining an API Key

1

Request Access

Contact your account manager to enable API access for your organization
2

Generate Key

Log in to AllCare Dashboard:
  1. Navigate to Settings > API Access
  2. Click “Generate New API Key”
  3. Provide a descriptive name
  4. Set permissions and scopes
  5. Copy the key immediately (shown only once)
3

Store Securely

Store the API key in a secure location:
  • Environment variables
  • Secrets management service (AWS Secrets Manager, Azure Key Vault, etc.)
  • Never commit to source control

​
Using API Keys

Include the API key in the Authorization header of each request: 
curl -X GET "https://api.allcare.ai/v1/doctors" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"
Header Format: 
Authorization: Bearer {API_KEY}

​
API Key Scopes

API keys can be configured with specific permissions:
ScopeDescriptionAccess Level
read:doctorsRead provider dataRead-only
write:doctorsCreate/update providersRead-write
read:patientsRead patient dataRead-only
write:patientsCreate/update patientsRead-write
read:facilitiesRead facility dataRead-only
write:facilitiesManage facilitiesRead-write
adminFull accessAll operations
Follow the principle of least privilege - grant only the minimum scopes required for your integration.

​
OAuth 2.0 Authentication

For applications that access AllCare on behalf of users:

​
OAuth Flow

1

Register Application

Register your application in the AllCare Developer Portal:
  • Application name
  • Redirect URI(s)
  • Requested scopes
You’ll receive:
  • Client ID
  • Client Secret
2

Authorization Request

Redirect user to authorization endpoint:
https://auth.allcare.ai/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read:patients write:prescriptions&
  state=RANDOM_STRING
3

User Authorizes

User logs in and approves access to requested scopes
4

Receive Authorization Code

User is redirected back to your application:
https://yourapp.com/callback?
  code=AUTHORIZATION_CODE&
  state=RANDOM_STRING
5

Exchange for Access Token

Exchange authorization code for access token:
curl -X POST "https://auth.allcare.ai/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=YOUR_REDIRECT_URI"
Response:
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def502009a8f7e...",
  "scope": "read:patients write:prescriptions"
}
6

Use Access Token

Include token in API requests:
curl -X GET "https://api.allcare.ai/v1/patients/12345" \
  -H "Authorization: Bearer ACCESS_TOKEN"

​
Refreshing Tokens

Access tokens expire after 1 hour. Use refresh token to obtain new access token: 
curl -X POST "https://auth.allcare.ai/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

​
Security Best Practices

​
Key Management

​
Rotating Keys

To rotate an API key:
  1. Generate new key in dashboard
  2. Update application with new key
  3. Test thoroughly
  4. Revoke old key
  5. Monitor for any issues
Keep both keys active during transition period to avoid downtime.

​
Revoking Keys

Revoke keys immediately if:
  • Key is compromised or exposed
  • Employee with key access leaves organization
  • Integration is deprecated
  • Suspicious activity detected
Revoke in Dashboard: Settings > API Access > Revoke

​
Testing Authentication

​
Verify API Key

Test your API key: 
curl -X GET "https://api.allcare.ai/v1/auth/verify" \
  -H "Authorization: Bearer YOUR_API_KEY"
Success response: 
{
  "valid": true,
  "scopes": ["read:doctors", "write:doctors"],
  "expires_at": "2025-12-31T23:59:59Z",
  "organization": "Your Organization"
}

​
Error Responses

​
401 Unauthorized

Missing or invalid credentials: 
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
Solution: Check API key is correct and included in Authorization header

​
403 Forbidden

Insufficient permissions: 
{
  "error": "FORBIDDEN",
  "message": "Insufficient permissions for this operation",
  "required_scope": "write:patients"
}
Solution: Request additional scopes or use key with appropriate permissions

​
429 Rate Limit Exceeded

Too many requests: 
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "retry_after": 60
}
Solution: Implement exponential backoff and respect rate limits

​
Support

Need help with authentication?

Developer Support

Email: [email protected]Include:
  • Client ID (never send client secret!)
  • Error messages
  • Request/response examples (remove credentials)