Authentication

The Jump EHR API uses API keys to authenticate requests. You can create and manage your API keys in the Jump EHR dashboard.

API Keys

All API requests require a valid API key passed in the Authorization header:

Authorization: Bearer pk_live_your_api_key

Key Types

Jump EHR provides two types of API keys:

Type	Prefix	Purpose
Test	`pk_test_`	Development and testing. Uses sandbox data.
Live	`pk_live_`	Production use. Accesses real patient data.

⚠️

Live API keys provide access to real patient data. Only use them in secure server-side environments.

Creating API Keys

Log in to your Jump EHR dashboard
Navigate to Settings > API Keys
Click Create API Key
Enter a descriptive name (e.g., "Production Backend", "Development")
Select the mode (Test or Live)
Choose the required scopes
Click Create

Your API key will only be displayed once. Copy it immediately and store it securely.

Revoking Keys

You can revoke an API key at any time from the dashboard. Revoked keys will immediately stop working for all API requests.

Authentication Examples

curl -X GET "https://app.usejump.co.uk/functions/v1/api-v1/patients" \
  -H "Authorization: Bearer pk_live_your_api_key"

JavaScript

const response = await fetch(
  'https://app.usejump.co.uk/functions/v1/api-v1/patients',
  {
    headers: {
      'Authorization': 'Bearer pk_live_your_api_key',
      'Content-Type': 'application/json'
    }
  }
);

Python

import requests
 
response = requests.get(
    'https://app.usejump.co.uk/functions/v1/api-v1/patients',
    headers={
        'Authorization': 'Bearer pk_live_your_api_key',
        'Content-Type': 'application/json'
    }
)

Scopes

API keys are assigned scopes that control which resources they can access. Request only the scopes your application needs.

Core Resource Scopes

Scope	Description
`read_patients`	View patient records and demographics
`write_patients`	Create and update patient records
`read_appointments`	View appointment records
`write_appointments`	Create, update, and cancel appointments
`read_episodes`	View episodes and episode events
`write_episodes`	Create episodes, add events, close/reopen/assign
`read_questionnaires`	View questionnaire templates and responses
`write_questionnaires`	Create and update questionnaire responses

Configuration Scopes

Scope	Description
`read_appointment_templates`	View appointment type configuration
`write_appointment_templates`	Create and update appointment templates
`read_pathways`	View pathway configs and rules
`write_pathways`	Update pathway configs, manage pathway rules

Read-Only Resource Scopes

Scope	Description
`read_consultations`	View consultation records and clinical sections
`read_locations`	View practice locations
`read_clinician_profiles`	View clinician profiles and booking status
`read_availability`	Query booking slot availability

Webhook Scopes

Scope	Description
`manage_webhooks`	Create, update, delete, and test webhook endpoints

Some scopes cover related resources. read_episodes / write_episodes grants access to both /episodes and /episode-events. read_questionnaires / write_questionnaires covers both templates and responses. read_pathways / write_pathways covers both configs and rules.

API keys default to ['read_patients'] if no scopes are specified during creation. Request only the scopes your application actually needs.

Authentication Errors

Status Code	Error Code	Description
`401`	`UNAUTHORISED`	Missing or invalid API key
`403`	`FORBIDDEN`	Valid key but missing required scope

Error Response

{
  "data": null,
  "meta": { "request_id": "req_abc123" },
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing required scope: 'read_episodes'. Your API key has scopes: [read_patients]."
  }
}

Security Best Practices

Following these practices helps protect your API keys and patient data.

Never expose keys in client-side code - API keys should only be used in server-side applications
Use environment variables - Store keys in environment variables, not in source code
Rotate keys regularly - Create new keys periodically and revoke old ones
Use minimal scopes - Only request the scopes your application actually needs
Monitor usage - Review API logs for unexpected activity
Use test keys for development - Only use live keys in production environments

Next Steps

Learn about Rate Limits and usage quotas
Explore the API Reference for endpoint details

Quickstart Rate Limits & Errors