Provider Credentials Standard

This document defines the standardized approach for documenting API credentials and provider information in OpenPets packages.

Overview

The new standard separates provider definitions from environment variables, making it easier to:

• Reuse provider information across multiple environment variables
• Maintain consistent credentialsUrl links
• Provide better documentation for users

Structure

1. Providers Array

Define providers in a separate providers array in package.json:

{
  "providers": [
    {
      "id": "google-maps",
      "name": "Google Maps Platform",
      "credentialsUrl": "https://console.cloud.google.com/apis/credentials",
      "credentialsDocUrl": "https://developers.google.com/maps/documentation/javascript/get-api-key"
    }
  ]
}

Required Fields

• id (string): Unique identifier for the provider
• credentialsUrl (string): Direct link to generate/manage API credentials

Recommended Fields

• name (string): Human-readable provider name
• credentialsDocUrl (string): Link to documentation about obtaining credentials

2. Environment Variables

Reference providers using providerId in envVariables:

{
  "envVariables": {
    "required": [
      {
        "name": "GOOGLE_MAPS_API_KEY",
        "description": "API key for Google Maps Platform",
        "providerId": "google-maps",
        "priority": 1
      }
    ],
    "optional": []
  }
}

Required Fields

• name (string): Environment variable name
• description (string): What this variable is used for
• providerId (string): References a provider id from the providers array
• priority (number): Order of importance (lower = higher priority)

3. .env.example File

Document credentials with comments linking to the provider:

# Get your API key from: https://console.cloud.google.com/apis/credentials
# Documentation: https://developers.google.com/maps/documentation/javascript/get-api-key
GOOGLE_MAPS_API_KEY=your_api_key_here

Complete Example

package.json

{
  "$schema": "https://pets.raggle.co/config.json",
  "name": "openpets/example",
  "version": "1.0.0",
  "providers": [
    {
      "id": "google-maps",
      "name": "Google Maps Platform",
      "credentialsUrl": "https://console.cloud.google.com/apis/credentials",
      "credentialsDocUrl": "https://developers.google.com/maps/documentation/javascript/get-api-key"
    },
    {
      "id": "openai",
      "name": "OpenAI",
      "credentialsUrl": "https://platform.openai.com/api-keys",
      "credentialsDocUrl": "https://platform.openai.com/docs/quickstart"
    }
  ],
  "envVariables": {
    "required": [
      {
        "name": "GOOGLE_MAPS_API_KEY",
        "description": "API key for Google Maps Platform",
        "providerId": "google-maps",
        "priority": 1
      }
    ],
    "optional": [
      {
        "name": "OPENAI_API_KEY",
        "description": "OpenAI API key for enhanced features",
        "providerId": "openai",
        "priority": 2
      }
    ]
  }
}

.env.example

# Google Maps Platform API Key
# Get your API key from: https://console.cloud.google.com/apis/credentials
# Documentation: https://developers.google.com/maps/documentation/javascript/get-api-key
GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here

# Optional: OpenAI API Key
# Get your API key from: https://platform.openai.com/api-keys
# Documentation: https://platform.openai.com/docs/quickstart
OPENAI_API_KEY=your_openai_api_key_here

Validation Rules

The build system validates:

Providers Array

✅ Must be an array ✅ Each provider must have a unique id ⚠️ Warning if missing name ⚠️ Warning if missing credentialsUrl ⚠️ Warning if credentialsUrl is not a valid URL pattern

Environment Variables

✅ Each variable must have a name, description, providerId, and priority ✅ providerId must reference a valid provider id ⚠️ Warning if providerId is missing

.env.example File

⚠️ Warning if environment variables are missing from file ⚠️ Warning if credentials URL comment is missing

Migration from Old Format

Old Format (deprecated)

{
  "envVariables": {
    "required": [
      {
        "name": "API_KEY",
        "description": "Get from https://example.com/keys",
        "provider": {
          "name": "Example Service",
          "generateKeyLink": "https://example.com/keys"
        },
        "priority": 1
      }
    ]
  }
}

New Format (standardized)

{
  "providers": [
    {
      "id": "example-service",
      "name": "Example Service",
      "credentialsUrl": "https://example.com/keys"
    }
  ],
  "envVariables": {
    "required": [
      {
        "name": "API_KEY",
        "description": "API key for Example Service",
        "providerId": "example-service",
        "priority": 1
      }
    ]
  }
}

Benefits

1. Reusability: Define a provider once, reference it multiple times
2. Consistency: All credentials URLs are in one place
3. Clarity: Separation of concerns between providers and environment variables
4. Validation: Better validation and error messages
5. Documentation: Easier to maintain and update provider information

Special Cases

Dynamic URLs with Placeholders

Providers can use placeholders in credentialsUrl:

{
  "id": "polar",
  "name": "Polar",
  "credentialsUrl": "https://polar.sh/dashboard/{POLAR_ORG_SLUG}/settings"
}

The validation system will properly handle URL patterns with {PLACEHOLDER} syntax.

Multiple Credentials from Same Provider

{
  "providers": [
    {
      "id": "jira",
      "name": "Atlassian Jira",
      "credentialsUrl": "https://id.atlassian.com/manage-profile/security/api-tokens",
      "credentialsDocUrl": "https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/"
    }
  ],
  "envVariables": {
    "required": [
      {
        "name": "JIRA_BASE_URL",
        "description": "Your Jira instance URL",
        "providerId": "jira",
        "priority": 1
      },
      {
        "name": "JIRA_EMAIL",
        "description": "Your Jira account email",
        "providerId": "jira",
        "priority": 2
      },
      {
        "name": "JIRA_API_TOKEN",
        "description": "API token for authentication",
        "providerId": "jira",
        "priority": 3
      }
    ]
  }
}