Tidepool API

https://tidepool.stoplight.io/
Admin
Tidepool is a nonprofit organization committed to making diabetes data accessible, actionable, and...
Tokens:4,780
Snippets:13
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Bash Example for Tidepool Client Registration Data

Source: https://context7.com/context7/tidepool_stoplight_io/llms.txt

Illustrates the JSON structure required when registering a third-party application with Tidepool for OAuth2 API access. This includes application details, redirect URIs, requested scopes, and contact information.

```bash
# Contact Tidepool to register your application
# Email: support@tidepool.org
# Slack: #opensource channel

# Registration request should include:
# - Application name
# - Application description
# - Redirect URIs
# - Required scopes
# - Contact information

# Example registration data
{
  "applicationName": "DiabetesTracker Pro",
  "description": "Mobile app for tracking diabetes metrics",
  "redirectUris": [
    "https://diabetestracker.com/callback",
    "myapp://oauth/callback"
  ],
  "scopes": ["openid", "profile", "email", "diabetes_data"],
  "contacts": [
    {
      "name": "John Developer",
      "email": "john@diabetestracker.com"
    }
  ],
  "environment": "int"  // Start with integration
}

# Tidepool will provide:
{
  "clientId": "dt_pro_12345",
  "clientSecret": "secret_abc123xyz789",  // If confidential client
  "allowedScopes": ["openid", "profile", "email", "diabetes_data"],
  "tokenEndpoint": "https://int-api.tidepool.org/oauth2/token",
  "authEndpoint": "https://int-api.tidepool.org/oauth2/authorize"
}
```

--------------------------------

### Tidepool API Environment Configuration - JavaScript

Source: https://context7.com/context7/tidepool_stoplight_io/llms.txt

Defines configuration objects for different Tidepool API environments: development, integration, and production. Each environment specifies API and upload URLs, stability, and data retention policies. An example demonstrates initializing an API client for the integration environment.

```javascript
// Environment configuration for API clients
const TIDEPOOL_ENVIRONMENTS = {
  // Internal development - DO NOT USE
  dev: {
    api: 'https://dev-api.tidepool.org',
    upload: 'https://dev-uploads.tidepool.org',
    stability: 'unstable',
    dataRetention: 'none'
  },

  // Integration testing - proof-of-concept only
  int: {
    api: 'https://int-api.tidepool.org',
    upload: 'https://int-uploads.tidepool.org',
    stability: 'testing',
    dataRetention: 'temporary',
    notes: 'Create separate test accounts, no production data'
  },

  // Production - only after integration testing
  prd: {
    api: 'https://api.tidepool.org',
    upload: 'https://uploads.tidepool.org',
    stability: 'stable',
    dataRetention: 'permanent'
  }
};

// Example: Configure API client for integration environment
const apiClient = new TidepoolClient({
  baseUrl: TIDEPOOL_ENVIRONMENTS.int.api,
  uploadUrl: TIDEPOOL_ENVIRONMENTS.int.upload
});
```

--------------------------------

### Environment Configuration

Source: https://context7.com/context7/tidepool_stoplight_io/llms.txt

Provides configuration details for different Tidepool API environments, including development, integration testing, and production.

```APIDOC
## Environment Configuration

### Description
Details on how to configure API clients for various Tidepool environments.

### Overview
Tidepool offers different environments for development, testing, and production.

### Environments
- **dev** (Internal development - DO NOT USE)
  - `api`: `https://dev-api.tidepool.org`
  - `upload`: `https://dev-uploads.tidepool.org`
  - `stability`: `unstable`
  - `dataRetention`: `none`

- **int** (Integration testing - proof-of-concept only)
  - `api`: `https://int-api.tidepool.org`
  - `upload`: `https://int-uploads.tidepool.org`
  - `stability`: `testing`
  - `dataRetention`: `temporary`
  - `notes`: Create separate test accounts, no production data

- **prd** (Production - only after integration testing)
  - `api`: `https://api.tidepool.org`
  - `upload`: `https://uploads.tidepool.org`
  - `stability`: `stable`
  - `dataRetention`: `permanent`

### Example Usage (JavaScript)
```javascript
// Environment configuration for API clients
const TIDEPOOL_ENVIRONMENTS = {
  dev: {
    api: 'https://dev-api.tidepool.org',
    upload: 'https://dev-uploads.tidepool.org',
    stability: 'unstable',
    dataRetention: 'none'
  },
  int: {
    api: 'https://int-api.tidepool.org',
    upload: 'https://int-uploads.tidepool.org',
    stability: 'testing',
    dataRetention: 'temporary',
    notes: 'Create separate test accounts, no production data'
  },
  prd: {
    api: 'https://api.tidepool.org',
    upload: 'https://uploads.tidepool.org',
    stability: 'stable',
    dataRetention: 'permanent'
  }
};

// Example: Configure API client for integration environment
// Assuming TidepoolClient is a hypothetical client class
// const apiClient = new TidepoolClient({
//   baseUrl: TIDEPOOL_ENVIRONMENTS.int.api,
//   uploadUrl: TIDEPOOL_ENVIRONMENTS.int.upload
// });
```
```

--------------------------------

### Tidepool API Overview

Source: https://tidepool.stoplight.io/index

Provides an overview of the Tidepool API, its purpose, and the distinction between public and full API access.

```APIDOC
## Tidepool API Overview

### Description
Tidepool's API is designed to make diabetes data accessible, actionable, and meaningful. The API is available in two views: the Public API, accessible to everyone and used by Tidepool's customer-facing products, and the Full API, which includes all of Tidepool's private APIs not accessible outside of Tidepool.

Tidepool is committed to transparency and open-source principles, with all products released under BSD-2 or MIT licenses.

### Key Information
- **Company Mission**: To help people with insulin-requiring diabetes achieve great outcomes through accessible, actionable, and meaningful diabetes data.
- **Data Focus**: Harnessing technology to provide intuitive software products for diabetes management.
- **Open Source**: All products are open source.

### API Views
- **Public API**: Tidepool APIs available to everyone. These are the APIs used by Tidepool's own customer-facing products.
- **Full API**: All of Tidepool's APIs, including those only available between services within their AWS VPC, requiring privileged access, or not generally useful outside of Tidepool. Included for internal reference and transparency.

### Deprecation Warning: Authentication APIs
The current authentication APIs are being deprecated and will be replaced by industry-standard OAuth2 and OpenID Connect APIs. This change aims to provide a consistent and secure sign-up and sign-in experience, including enterprise Single Sign-On (SSO).
- **Deprecation Timeline**: Expected to be fully removed by the end of 2023.
```

--------------------------------

### Register New User Account - cURL

Source: https://context7.com/context7/tidepool_stoplight_io/llms.txt

Allows new users to create an account in the Tidepool workspace. This operation requires a POST request to the signup endpoint with a JSON payload containing username, password, emails, and roles. The response confirms account creation with basic user details.

```bash
# Create new user account
curl -X POST https://api.tidepool.org/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser@example.com",
    "password": "securePassword789",
    "emails": ["newuser@example.com"],
    "roles": ["patient"]
  }'

# Response
{
  "userid": "xyz789abc123",
  "username": "newuser@example.com",
  "emails": ["newuser@example.com"],
  "emailVerified": false,
  "created": "2023-06-15T14:22:00Z"
}

# Note: Join requests may be disabled for workspaces
# Users can only join if invited or email domain is allowed
```

--------------------------------

### Tidepool API Environments

Source: https://tidepool.stoplight.io/index

Details the different environments available for developing and testing applications that use the Tidepool API.

```APIDOC
## Tidepool API Environments

### Description
This section outlines the different environments available for developing and testing applications that interact with the Tidepool API. Developers are encouraged to use the integration environment for testing before moving to production.

### Environments

#### Development (`dev`, `qa1`, `qa2`)
- **Description**: These environments are intended for Tidepool's internal development use only. They are subject to constant change and testing, with no guarantees for privacy or stability of accounts or data.
- **Usage**: **Do not use these environments at all**.

#### Integration (`int`)
- **Description**: This environment is for development proof-of-concept tests only. It is not intended for production data. There are no guarantees for privacy or stability of accounts or data.
- **Usage**: **Do not use it for production data**.
- **Access**: To use the integration environment, you need to create accounts on this environment and upload data through it. For example, before logging into the Tidepool Uploader, right-click and set the server to 'integration'.
- **Review Process**: After testing on the integration environment, inform Tidepool for review of plans to move to the production environment.

#### Production (`prd`)
- **Description**: The official production environment for live data and applications.
- **Usage**: **Please do not use the production environment during your development**. Only use the integration environment or your own local back-end server environment for development.
```

--------------------------------

### Authentication - User Registration API

Source: https://context7.com/context7/tidepool_stoplight_io/llms.txt

Facilitates the creation of new user accounts within the Tidepool workspace, requiring user details and role assignments.

```APIDOC
## POST /auth/signup

### Description
Creates a new user account for the Tidepool workspace.

### Method
POST

### Endpoint
`https://api.tidepool.org/auth/signup`

### Parameters
#### Request Body
- **username** (string) - Required - The email address for the new user.
- **password** (string) - Required - The desired password for the new account.
- **emails** (array of strings) - Required - A list containing the user's email address.
- **roles** (array of strings) - Required - Roles to assign to the user (e.g., "patient").

### Request Example
```json
{
  "username": "newuser@example.com",
  "password": "securePassword789",
  "emails": ["newuser@example.com"],
  "roles": ["patient"]
}
```

### Response
#### Success Response (200)
- **userid** (string) - The unique identifier for the newly created user.
- **username** (string) - The email address of the new user.
- **emails** (array of strings) - The email addresses provided for the new user.
- **emailVerified** (boolean) - Indicates if the user's email has been verified (initially false).
- **created** (string) - ISO 8601 timestamp of when the account was created.

#### Response Example
```json
{
  "userid": "xyz789abc123",
  "username": "newuser@example.com",
  "emails": ["newuser@example.com"],
  "emailVerified": false,
  "created": "2023-06-15T14:22:00Z"
}
```

### Notes
- Joining requests may be disabled for specific workspaces.
- Users can only join if invited or if their email domain is allowed.
```

--------------------------------

### Authentication - Email Login API

Source: https://context7.com/context7/tidepool_stoplight_io/llms.txt

Authenticates users using their email and password credentials to access the Tidepool workspace. It returns user details and a session token.

```APIDOC
## POST /auth/login

### Description
Authenticates a user with email and password.

### Method
POST

### Endpoint
`https://api.tidepool.org/auth/login`

### Parameters
#### Request Body
- **username** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "username": "user@example.com",
  "password": "securePassword123"
}
```

### Response
#### Success Response (200)
- **userid** (string) - The unique identifier for the user.
- **username** (string) - The user's email address.
- **emails** (array of strings) - A list of the user's email addresses.
- **roles** (array of strings) - The roles assigned to the user.
- **termsAccepted** (string) - ISO 8601 timestamp when terms were accepted.
- **emailVerified** (boolean) - Indicates if the user's email has been verified.

#### Response Example
```json
{
  "userid": "abc123def456",
  "username": "user@example.com",
  "emails": ["user@example.com"],
  "roles": ["patient"],
  "termsAccepted": "2023-01-15T10:30:00Z",
  "emailVerified": true
}
```

### Response Headers
- **x-tidepool-session-token** (string) - The session token for subsequent authenticated requests.
```

--------------------------------

### Authenticate User with Email and Password - cURL

Source: https://context7.com/context7/tidepool_stoplight_io/llms.txt

Logs a user into the Tidepool workspace using their email and password. It requires a POST request to the authentication endpoint with JSON payload containing username and password. The response includes user details and a session token in the headers.

```bash
# Login with email and password
curl -X POST https://api.tidepool.org/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user@example.com",
    "password": "securePassword123"
  }'

# Expected Response
{
  "userid": "abc123def456",
  "username": "user@example.com",
  "emails": ["user@example.com"],
  "roles": ["patient"],
  "termsAccepted": "2023-01-15T10:30:00Z",
  "emailVerified": true
}

# Response Headers include:
# x-tidepool-session-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

--------------------------------

### JavaScript OAuth2 Authorization Code Flow for Tidepool

Source: https://context7.com/context7/tidepool_stoplight_io/llms.txt

Implements the OAuth2 authorization code grant flow for third-party applications to access Tidepool user data. Requires client credentials and handles redirection, token exchange, and API calls. Assumes browser environment for redirection.

```javascript
// OAuth2 authorization code flow
const oauth2Config = {
  clientId: 'your-client-id',  // Request from Tidepool
  redirectUri: 'https://yourapp.com/callback',
  authEndpoint: 'https://api.tidepool.org/oauth2/authorize',
  tokenEndpoint: 'https://api.tidepool.org/oauth2/token',
  scopes: ['openid', 'profile', 'email', 'diabetes_data']
};

// Step 1: Redirect user to authorization endpoint
const authUrl = `${oauth2Config.authEndpoint}?` +
  `client_id=${oauth2Config.clientId}&` +
  `redirect_uri=${encodeURIComponent(oauth2Config.redirectUri)}&` +
  `response_type=code&` +
  `scope=${oauth2Config.scopes.join(' ')}`;

window.location.href = authUrl;

// Step 2: Handle callback and exchange code for tokens
async function handleCallback(authCode) {
  const response = await fetch(oauth2Config.tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded'
    },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code: authCode,
      redirect_uri: oauth2Config.redirectUri,
      client_id: oauth2Config.clientId
    })
  });

  const tokens = await response.json();
  // {
  //   access_token: 'eyJhbGc...',
  //   refresh_token: 'RT_abc123...',
  //   token_type: 'Bearer',
  //   expires_in: 3600,
  //   id_token: 'eyJhbGc...'
  // }

  return tokens;
}

// Step 3: Use access token for API requests
async function fetchUserData(accessToken) {
  const response = await fetch('https://api.tidepool.org/v1/users/me', {
    headers: {
      'Authorization': `Bearer ${accessToken}`
    }
  });

  return await response.json();
}
```

--------------------------------

### Authentication - Password Reset API

Source: https://context7.com/context7/tidepool_stoplight_io/llms.txt

Handles the password reset process for users who have forgotten their credentials. It involves requesting a reset code and then submitting the code with a new password.

```APIDOC
## POST /auth/forgot and POST /auth/reset

### Description
Allows users to reset their forgotten passwords through a two-step process involving a reset code.

### Method
POST

### Endpoint
- **Request Code**: `https://api.tidepool.org/auth/forgot`
- **Reset Password**: `https://api.tidepool.org/auth/reset`

### Parameters
#### Request Body (for POST /auth/forgot)
- **email** (string) - Required - The email address associated with the account.

#### Request Body (for POST /auth/reset)
- **email** (string) - Required - The email address associated with the account.
- **code** (string) - Required - The password reset code sent to the user's email.
- **password** (string) - Required - The new password for the account.

### Request Example (Request Code)
```json
{
  "email": "user@example.com"
}
```

### Request Example (Reset Password)
```json
{
  "email": "user@example.com",
  "code": "ABC123",
  "password": "newSecurePassword456"
}
```

### Response
#### Success Response (200) for POST /auth/forgot
- **status** (string) - Indicates the status of the request (e.g., "success").
- **message** (string) - A confirmation message (e.g., "Reset code sent to user@example.com").

#### Success Response (200) for POST /auth/reset
- **status** (string) - Indicates the status of the request (e.g., "success").
- **message** (string) - A confirmation message (e.g., "Password successfully reset").

#### Response Example (for POST /auth/forgot)
```json
{
  "status": "success",
  "message": "Reset code sent to user@example.com"
}
```

#### Response Example (for POST /auth/reset)
```json
{
  "status": "success",
  "message": "Password successfully reset"
}
```
```

--------------------------------

### JavaScript API Error Handling and Custom Error Class

Source: https://context7.com/context7/tidepool_stoplight_io/llms.txt

Defines a custom `TidepoolApiError` class to represent API errors with status, code, and details. Includes a function `apiRequestWithErrorHandling` that handles common HTTP error codes (401, 403, 404, 429, 500, 502, 503) by logging, throwing specific errors, or retrying requests. It also demonstrates usage with a try-catch block for handling potential API request failures.

```javascript
class TidepoolApiError extends Error {
  constructor(response, body) {
    super(body.message || 'API request failed');
    this.status = response.status;
    this.code = body.code;
    this.details = body.details;
  }
}

async function apiRequestWithErrorHandling(url, options) {
  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 401:
          console.error('Authentication failed:', error.message);
          await refreshAccessToken();
          break;

        case 403:
          console.error('Access denied:', error.message);
          throw new TidepoolApiError(response, error);

        case 404:
          console.error('Resource not found:', error.message);
          return null;

        case 429:
          const retryAfter = response.headers.get('Retry-After');
          console.warn(`Rate limited. Retry after ${retryAfter}s`);
          await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
          return apiRequestWithErrorHandling(url, options);

        case 500:
        case 502:
        case 503:
          console.error('Server error:', error.message);
          throw new TidepoolApiError(response, error);

        default:
          throw new TidepoolApiError(response, error);
      }
    }

    return await response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

try {
  const userData = await apiRequestWithErrorHandling(
    'https://api.tidepool.org/v1/users/me',
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      }
    }
  );
  console.log('User data:', userData);
} catch (error) {
  if (error instanceof TidepoolApiError) {
    console.error(`API Error ${error.status}: ${error.message}`);
  } else {
    console.error('Request failed:', error);
  }
}
```

--------------------------------

### Reset User Password - cURL

Source: https://context7.com/context7/tidepool_stoplight_io/llms.txt

Facilitates password recovery for users. It involves two steps: requesting a reset code via email, and then resetting the password using the received code. Both steps require POST requests with specific JSON payloads.

```bash
# Step 1: Request password reset code
curl -X POST https://api.tidepool.org/auth/forgot \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

# Response
{
  "status": "success",
  "message": "Reset code sent to user@example.com"
}

# Step 2: Reset password with code (sent via email)
curl -X POST https://api.tidepool.org/auth/reset \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "code": "ABC123",
    "password": "newSecurePassword456"
  }'

# Response
{
  "status": "success",
  "message": "Password successfully reset"
}
```
Tokens:
Raw