Authentication

API Keys

All requests to the Telesoft API must include an API key for authentication. Your API key carries many privileges, so be sure to keep it secure.

Key Types

Using Your API Key

Include your API key in the Authorization header of all requests:

// HTTP Header
Authorization: Bearer ts_live_xxxxxxxxxxxxxxxxxxxxxxxxxxx

OAuth 2.0 Authentication

For applications that need to access the Telesoft API on behalf of users, we support the OAuth 2.0 protocol. This allows users to authorize your application without sharing their credentials.

OAuth Flow

1. Register your application

   Create an OAuth application in the Telesoft Developer Portal to receive your client ID and secret.

2. Request authorization

   Redirect users to our authorization URL with your client ID and requested scopes.

3. Receive authorization code

   After the user approves, we'll redirect back to your application with an authorization code.

4. Exchange for access token

   Exchange the authorization code for an access token using your client secret.

5. Make API requests

   Use the access token to make API requests on behalf of the user.

Example OAuth Flow

// 1. Redirect user to authorization URL
const authUrl = 'https://auth.telesoft.us/oauth/authorize';
const params = new URLSearchParams({
  client_id: 'YOUR_CLIENT_ID',
  redirect_uri: 'https://your-app.com/callback',
  response_type: 'code',
  scope: 'read:patient_data write:medical_records',
  state: 'random_state_for_csrf_protection'
});

window.location.href = `${authUrl}?${params.toString()}`;

// 2. In your callback handler, exchange the code for a token
async function handleCallback(code) {
  const tokenUrl = 'https://auth.telesoft.us/oauth/token';
  const response = await fetch(tokenUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      grant_type: 'authorization_code',
      code: code,
      redirect_uri: 'https://your-app.com/callback'
    })
  });
  
  const data = await response.json();
  // Store the tokens securely
  const accessToken = data.access_token;
  const refreshToken = data.refresh_token;
  
  // 3. Use the access token for API requests
  const apiResponse = await fetch('https://api.telesoft.us/v2/patient/summary', {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });
  
  const patientData = await apiResponse.json();
  return patientData;
}

Access Token Management

OAuth access tokens are valid for 2 hours. After expiration, you'll need to use a refresh token to obtain a new access token without requiring the user to re-authorize.

Refreshing Tokens

async function refreshAccessToken(refreshToken) {
  const tokenUrl = 'https://auth.telesoft.us/oauth/token';
  const response = await fetch(tokenUrl, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      client_id: 'YOUR_CLIENT_ID',
      client_secret: 'YOUR_CLIENT_SECRET',
      grant_type: 'refresh_token',
      refresh_token: refreshToken
    })
  });
  
  const data = await response.json();
  return {
    accessToken: data.access_token,
    refreshToken: data.refresh_token // A new refresh token is issued
  };
}

Scopes

OAuth scopes define the specific permissions your application can request from users. Always request the minimum scopes necessary for your application.

HIPAA Compliance

Applications using Telesoft APIs to process, store, or transmit Protected Health Information (PHI) must comply with HIPAA regulations.

Advanced Security Features

// Example API key configuration with IP restrictions
{
  "key_id": "key_5f9a2d7e8b3c",
  "name": "Production API Key",
  "allowed_ips": [
    "203.0.113.0/24",
    "198.51.100.42"
  ],
  "created_at": "2025-01-15T09:23:45Z"
}

// Verifying webhook signatures (Node.js example)
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(digest),
    Buffer.from(signature)
  );
}

// In your webhook handler
const isValid = verifyWebhookSignature(
  JSON.stringify(req.body),
  req.headers['telesoft-signature'],
  process.env.WEBHOOK_SECRET
);

if (!isValid) {
  return res.status(401).send('Invalid signature');
}