API Key Management

API access is managed at the organisation level. Your root API key is the management key for that organisation: use it to inspect keys, provision child API keys, update limits, and revoke child API keys.A child API key is the runtime credential used by one downstream application, workflow, or customer environment.Child API keys can be left unrestricted, or capped by one or more monthly limits. Use usage_limit for request count, monthly_token_limit for LLM tokens, and monthly_stt_secs_limit for speech transcription seconds. If you omit all three limit fields when creating a child API key, that key is created without child-key limits. If you set any one of them, only the supplied dimensions are enforced and omitted dimensions stay unrestricted.

GET /api/v1/api-key

Retrieves the authenticated key. Root keys can also use list_all=true to list every key in the organisation. The list-all response is an object keyed by API key ID.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Api-Keystring

Your API key for authentication.

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

QUERY PARAMETERS

OPTIONALlist_allstring

Optional. Set to "true" to list all API keys for the organisation. Requires a root API key.

Error Codes4 cases

Common API key authentication errors

400	Provider ID is invalid.	The X-Scrubs-Clinic-Provider header does not map to a known organisation.
401	API key authentication failed.	The API key or provider header is missing, or the supplied API key is invalid for the provider.
500	Unexpected server failure.	Repository, database, or service errors while reading or mutating API key data.

List all validation

403

Root API key is required for list_all=true.

A non-root key can retrieve only its own key metadata.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

Node.JS

Python

CURL

1curl --location --request GET 'https://usescrubs.com/api/v1/api-key' \
2--header 'X-Scrubs-Clinic-Api-Key: your_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id'
4
5# To list all API keys (requires root key):
6curl --location --request GET 'https://usescrubs.com/api/v1/api-key?list_all=true' \
7--header 'X-Scrubs-Clinic-Api-Key: your_root_api_key_here' \
8--header 'X-Scrubs-Clinic-Provider: your_provider_id'

Sample Response

JSON

1{
2  "id": "key_123456789",
3  "friendly_name": "Production EHR Integration",
4  "created": "2024-01-15T10:30:00Z",
5  "usage_limit": 1000,
6  "monthly_stt_secs_limit": 7200,
7  "monthly_token_limit": 5000000,
8  "root": false
9}

POST /api/v1/api-key

Provisions a new child API key. This endpoint requires a root API key. Any internal linkage needed by the platform is created automatically.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Api-Keystring

Your API key for authentication.

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

BODY PARAMETERS

REQUIREDfriendly_namestring

A human-readable label to help you recognise this key later.

OPTIONALusage_limitnumber

Optional. Monthly request limit for this API key. Leave it out to keep request usage unrestricted unless you want to cap requests explicitly.

OPTIONALmonthly_token_limitnumber

Optional. Monthly LLM token cap for this API key. Leave it out to keep token usage unrestricted.

OPTIONALmonthly_stt_secs_limitnumber

Optional. Monthly speech-to-text cap for this API key, in seconds. Leave it out to keep STT usage unrestricted.

Error Codes7 cases

Request validation

400

Request body is invalid.

friendly_name is required. usage_limit, monthly_token_limit, and monthly_stt_secs_limit must be numeric when provided.

Common API key authentication errors

400	Provider ID is invalid.	The X-Scrubs-Clinic-Provider header does not map to a known organisation.
401	API key authentication failed.	The API key or provider header is missing, or the supplied API key is invalid for the provider.
500	Unexpected server failure.	Repository, database, or service errors while reading or mutating API key data.

Root API key requirement

403

Root API key is required.

The authenticated key is valid but does not have root-level permission for this operation.

Creation validation

409	A conflicting managed key already exists.	The requested internal linkage is already in use within this organisation.
500	API key creation failed.	The key service did not return a new secret or an unexpected persistence error occurred.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

NodeJS

Python

CURL

1curl --location --request POST 'https://usescrubs.com/api/v1/api-key' \
2--header 'X-Scrubs-Clinic-Api-Key: your_root_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id' \
4--header 'Content-Type: application/json' \
5--data '{
6  "friendly_name": "Production EHR Integration",
7  "usage_limit": 100,
8  "monthly_token_limit": 5000000,
9  "monthly_stt_secs_limit": 7200
10}'

Sample Response

JSON

1{
2  "apiKey": "sk_live_123456789abcdef",
3  "friendly_name": "Production EHR Integration",
4  "created": "2024-01-25T09:15:00Z",
5  "usage_limit": 100,
6  "monthly_stt_secs_limit": 7200,
7  "monthly_token_limit": 5000000,
8  "root": false
9}

PUT /api/v1/api-key

Updates the label or monthly limits on an existing key. Root keys can update their own record and child keys, but cannot modify a different root key.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Api-Keystring

Your API key for authentication.

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

BODY PARAMETERS

REQUIREDidstring

The ID of the API key to update.

OPTIONALfriendly_namestring

Optional. New label for the API key.

OPTIONALusage_limitnumber

Optional. New monthly request limit for the API key.

OPTIONALmonthly_token_limitnumber

Optional. New monthly LLM token cap.

OPTIONALmonthly_stt_secs_limitnumber

Optional. New monthly speech-to-text cap in seconds.

Error Codes7 cases

Request validation

400

Request body is invalid.

id is required. friendly_name, usage_limit, monthly_token_limit, and monthly_stt_secs_limit are optional, but numeric limits must be numbers when provided.

Common API key authentication errors

400	Provider ID is invalid.	The X-Scrubs-Clinic-Provider header does not map to a known organisation.
401	API key authentication failed.	The API key or provider header is missing, or the supplied API key is invalid for the provider.
500	Unexpected server failure.	Repository, database, or service errors while reading or mutating API key data.

Root API key requirement

403

Root API key is required.

The authenticated key is valid but does not have root-level permission for this operation.

Update validation

403	Cannot update another root key.	Root keys can update themselves and subkeys, but cannot update a different root key.
404	API key was not found.	The id in the request body does not match an API key.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

NodeJS

Python

CURL

1curl --location --request PUT 'https://usescrubs.com/api/v1/api-key' \
2--header 'X-Scrubs-Clinic-Api-Key: your_root_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id' \
4--header 'Content-Type: application/json' \
5--data '{
6  "id": "key_123456789",
7  "friendly_name": "Production EHR Integration",
8  "usage_limit": 1500,
9  "monthly_token_limit": 8000000,
10  "monthly_stt_secs_limit": 14400
11}'

Sample Response

JSON

1{
2  "id": "key_123456789",
3  "friendly_name": "Production EHR Integration",
4  "created": "2024-01-15T10:30:00Z",
5  "usage_limit": 1500,
6  "monthly_stt_secs_limit": 14400,
7  "monthly_token_limit": 8000000,
8  "root": false
9}

DELETE /api/v1/api-key

Deletes an API key. This endpoint requires a root API key and immediately revokes the specified child key.HEADER PARAMETERS

REQUIREDX-Scrubs-Clinic-Api-Keystring

Your API key for authentication.

REQUIREDX-Scrubs-Clinic-Providerstring

Provider ID associated with your EHR application.

QUERY PARAMETERS

REQUIREDidstring

The ID of the API key to delete.

Error Codes6 cases

Request validation

400

API key ID is missing.

The id query parameter is required.

Common API key authentication errors

400	Provider ID is invalid.	The X-Scrubs-Clinic-Provider header does not map to a known organisation.
401	API key authentication failed.	The API key or provider header is missing, or the supplied API key is invalid for the provider.
500	Unexpected server failure.	Repository, database, or service errors while reading or mutating API key data.

Root API key requirement

403

Root API key is required.

The authenticated key is valid but does not have root-level permission for this operation.

Deletion validation

404

API key was not found.

The id query parameter does not match an existing API key.

Domain

BASE URL

1https://usescrubs.com

Sample Request

CURL

NodeJS

Python

CURL

1curl --location --request DELETE 'https://usescrubs.com/api/v1/api-key?id=key_123456789' \
2--header 'X-Scrubs-Clinic-Api-Key: your_root_api_key_here' \
3--header 'X-Scrubs-Clinic-Provider: your_provider_id'

Sample Response

JSON

1{
2  "message": "API key deleted successfully"
3}