Interactor Credentials

When NOT to Use

• Internal service authentication: This skill is for external third-party services (Google, Slack, etc.), not Interactor-to-Interactor authentication
• One-time API calls: If you don't need persistent access, consider direct OAuth without credential storage
• Client-side usage: All Interactor API calls must be made from your backend (see Backend-Only Execution Model)

Prerequisites

• Interactor authentication configured (see interactor-auth skill)
• Understanding of OAuth 2.0 flows
• Namespace strategy for multi-tenant isolation

Overview

Interactor handles credential complexity for both OAuth tokens and API keys:

Architecture Concepts

Backend-Only Execution Model

Critical: All Interactor API calls must be made from your backend server.

Interactor does not authenticate your end users directly. Your application:

1. Authenticates users through your own auth system
2. Makes Interactor API calls on behalf of authenticated users
3. Never exposes Interactor tokens or credential IDs to the client

Never expose to client-side code:

• Interactor access tokens (your JWT)
• Credential IDs (cred_abc)
• External service access tokens (e.g., Google OAuth tokens)

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Browser/App   │     │   Your Backend  │     │   Interactor    │
│   (Frontend)    │     │   (Server)      │     │   API           │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │ User action           │                       │
         │──────────────────────>│                       │
         │                       │                       │
         │                       │ API call with JWT     │
         │                       │──────────────────────>│
         │                       │                       │
         │                       │ Credential/token      │
         │                       │<──────────────────────│
         │                       │                       │
         │ Response (no tokens)  │                       │
         │<──────────────────────│                       │

Namespace Patterns

Namespaces provide multi-tenant isolation for credentials. Interactor supports several strategies:

Namespace behavior:

// Per-user credential (isolated)
{ namespace: "user_123", service_id: "google_calendar" }

// Shared credential (accessible by multiple users)
{ namespace: "shared", service_id: "slack" }

// Account-level credential (omit namespace)
{ service_id: "salesforce" }  // Accessible to all API calls

Important: If namespace is omitted, credentials are created at the account level and are accessible to all API calls using that account's authentication.

Hybrid patterns:

• Shared read-only credentials + user-specific write credentials
• Organization-level defaults + user overrides
• Environment-based namespaces (prod_user_123, staging_user_123)

Credential Access Control

Note: Fine-grained access control (role-based permissions, credential-to-workflow binding) is managed at the account level through Interactor's admin interface. The API does not currently expose permission management endpoints.

Credentials within a namespace are accessible to any authenticated request that includes that namespace. For granular control:

• Use separate namespaces for different access levels
• Implement access control in your application layer
• Use Interactor's admin interface for account-level restrictions

Instructions

Step 1: List All Credentials

Get all credentials in your account:

curl https://core.interactor.com/api/v1/credentials \
  -H "Authorization: Bearer <token>"

Query Parameters:

Example - List credentials for a specific user:

curl "https://core.interactor.com/api/v1/credentials?namespace=user_123" \
  -H "Authorization: Bearer <token>"

Response (structure inferred from credential object pattern):

{
  "data": {
    "credentials": [
      {
        "id": "cred_abc",
        "service_id": "google_calendar",
        "service_name": "Google Calendar",
        "namespace": "user_123",
        "status": "active",
        "scopes": ["calendar.readonly", "calendar.events"],
        "created_at": "2026-01-15T10:00:00Z",
        "expires_at": "2026-02-01T00:00:00Z"
      }
    ]
  }
}

Step 2: Get Credentials Summary

Get a high-level summary grouped by namespace:

curl https://core.interactor.com/api/v1/credentials/summary \
  -H "Authorization: Bearer <token>"

Response:

{
  "data": {
    "namespaces": {
      "user_123": [
        {
          "id": "cred_abc",
          "service_id": "google_calendar",
          "service_name": "Google Calendar",
          "status": "active",
          "scopes": ["calendar.readonly", "calendar.events"],
          "expires_at": "2026-02-01T00:00:00Z"
        }
      ],
      "user_456": [
        {
          "id": "cred_def",
          "service_id": "slack",
          "service_name": "Slack",
          "status": "active",
          "scopes": ["channels:read", "chat:write"]
        }
      ]
    },
    "total_count": 2
  }
}

Step 3: Get a Specific Credential

curl https://core.interactor.com/api/v1/credentials/cred_abc \
  -H "Authorization: Bearer <token>"

Response (structure inferred from credential object pattern):

{
  "data": {
    "id": "cred_abc",
    "service_id": "google_calendar",
    "service_name": "Google Calendar",
    "namespace": "user_123",
    "status": "active",
    "scopes": ["calendar.readonly", "calendar.events"],
    "metadata": {
      "email": "[email protected]"
    },
    "created_at": "2026-01-15T10:00:00Z",
    "last_refreshed_at": "2026-01-20T11:00:00Z",
    "expires_at": "2026-02-01T00:00:00Z"
  }
}

Step 4: Get Access Token for External API

Retrieve the current access token. Automatically refreshes if expired.

curl https://core.interactor.com/api/v1/credentials/cred_abc/token \
  -H "Authorization: Bearer <token>"

Response:

{
  "data": {
    "access_token": "ya29.a0AfH6SM...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

Use this token to call the external service's API directly:

# Example: Call Google Calendar API
curl "https://www.googleapis.com/calendar/v3/calendars/primary/events" \
  -H "Authorization: Bearer ya29.a0AfH6SM..."

Step 5: Force Token Refresh

Manually trigger a token refresh:

curl -X POST https://core.interactor.com/api/v1/credentials/cred_abc/refresh \
  -H "Authorization: Bearer <token>"

Response (structure inferred):

{
  "data": {
    "id": "cred_abc",
    "status": "active",
    "last_refreshed_at": "2026-01-20T12:00:00Z"
  }
}

Step 6: Delete a Credential

Delete a credential (revokes OAuth tokens if applicable):

curl -X DELETE https://core.interactor.com/api/v1/credentials/cred_abc \
  -H "Authorization: Bearer <token>"

Response: 204 No Content on success.

OAuth Flow Implementation

Initiate OAuth Authorization

Start an OAuth flow to connect an external service:

curl -X POST https://core.interactor.com/api/v1/oauth/initiate \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "google_calendar",
    "namespace": "user_123",
    "scopes": ["calendar.readonly", "calendar.events"],
    "redirect_uri": "https://yourapp.com/oauth/callback"
  }'

Parameters:

Scope Validation & Mapping:

Interactor validates and maps scopes at different stages:

Interactor uses simplified scope identifiers that map to provider-specific OAuth URLs:

calendar.readonly  →  https://www.googleapis.com/auth/calendar.readonly