Terapi Integration Connection

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://github.com/api-evangelist/terapi/blob/main/json-schema/terapi-connection-schema.json",
  "title": "Terapi Integration Connection",
  "description": "Schema for an integration connection in Terapi, representing an authenticated link between an end-user and a third-party service.",
  "type": "object",
  "required": ["id", "provider_config_key", "provider"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Your application's unique identifier for this connection (set by you)"
    },
    "provider_config_key": {
      "type": "string",
      "description": "The integration provider configuration key this connection belongs to"
    },
    "provider": {
      "type": "string",
      "description": "The third-party provider name (e.g., github, salesforce, slack, hubspot)"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when the connection was created"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when the connection was last updated"
    },
    "metadata": {
      "type": "object",
      "description": "Custom metadata stored with this connection (e.g., user ID, tenant ID)",
      "additionalProperties": true
    },
    "credentials": {
      "type": "object",
      "description": "Current credential status (no raw secrets are returned)",
      "properties": {
        "type": {
          "type": "string",
          "description": "Type of credentials used",
          "enum": ["oauth2", "oauth1", "api_key", "basic", "custom"]
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "Token expiration time for OAuth credentials"
        }
      }
    }
  },
  "examples": [
    {
      "id": "user-123",
      "provider_config_key": "github-prod",
      "provider": "github",
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-05-03T08:00:00Z",
      "metadata": {
        "user_id": "user-123",
        "tenant_id": "acme-corp"
      },
      "credentials": {
        "type": "oauth2",
        "expires_at": "2026-05-04T08:00:00Z"
      }
    }
  ]
}