Skip to main content

Authentication

Learn how to authenticate with the Prospyr API to access patient data and practice management features.

Overview​

The Prospyr API uses Bearer token authentication for secure access. All requests must include a valid JWT token in the request headers along with the required app header.

Bearer Token Authentication​

Obtaining Your Token​

To get started with the Prospyr API, you'll need to obtain a JWT token. Contact the Prospyr team at gsupport@prospyrmed.com to request access credentials.

Using Your Token​

Include your token in all requests using the Authorization header with Bearer scheme, along with the app: "api" header:

curl -X POST https://prod.prospyrmedapi.com/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'app: "api"' \
  -d '{"query": "{ patient { id firstName lastName } }"}'

Security Best Practices​

  • Never expose your API key in client-side code or public repositories
  • Use environment variables to store your API key
  • Rotate your keys regularly for enhanced security
  • Use HTTPS for all API requests

Using JWT Tokens​

Once you have a JWT token, include it in the Authorization header along with the app header:

curl -X POST https://prod.prospyrmedapi.com/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'app: "api"' \
  -d '{"query": "{ patient(limit:10) { id firstName lastName} }"}'

Authentication in Different Environments​

Using Postman​

  1. Fork the Prospyr Public API Collection
  2. Go to the collection's Variables tab
  3. Set your JWT token in the token variable
  4. The collection will automatically include both the Authorization and app headers

Node.js Example​

const axios = require('axios');

const client = axios.create({
  baseURL: 'https://prod.prospyrmedapi.com/v1/graphql',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.PROSPYR_JWT_TOKEN}`,
    'app': 'api'
  }
});

// Make a request
async function getPatients() {
  const query = `
    query GetPatients {
      patientWorkspace(limit: 10) {
        id
        firstName
        lastName
        email
        phoneNumber
        patientId
      }
    }
  `;
  
  const response = await client.post('', { query });
  return response.data;
}

Python Example​

import os
import requests

headers = {
    'Content-Type': 'application/json',
    'Authorization': f"Bearer {os.environ.get('PROSPYR_JWT_TOKEN')}",
    'app': 'api'
}

query = """
query GetPatients {
  patient(limit: 10) {
    id
    firstName
    lastName
    dateOfBirth
  }
}
"""

response = requests.post(
    'https://prod.prospyrmedapi.com/v1/graphql',
    json={'query': query},
    headers=headers
)

data = response.json()

Error Handling​

Common Authentication Errors​

401 Unauthorized​

{
  "errors": [{
    "message": "Authorization header is missing or invalid",
    "extensions": {
      "code": "ACCESS_DENIED"
    }
  }]
}

Solution: Ensure your JWT token is correctly included in the Authorization header with Bearer scheme and the app header is set to "api".

403 Forbidden​

{
  "errors": [{
    "message": "Insufficient permissions",
    "extensions": {
      "code": "FORBIDDEN"
    }
  }]
}

Solution: Your token may not have access to the requested resource or the app header might be missing. Contact support for assistance.

Rate Limiting​

The Prospyr API implements rate limiting to ensure fair usage:

  • Default limit: 1000 requests per hour
  • Burst limit: 100 requests per minute
  • Rate limit headers are included in all responses:
    • X-RateLimit-Limit: Maximum requests per hour
    • X-RateLimit-Remaining: Requests remaining in current window
    • X-RateLimit-Reset: Time when the rate limit resets (Unix timestamp)

Next Steps​

Now that you're authenticated, you can: