Interactor Credential Management Skill

Securely store and manage OAuth tokens and API keys for external services through the Interactor platform.

When to Use

•Connecting External Services: When users need to connect Google, Slack, Salesforce, or other OAuth services
•OAuth Flow Implementation: Initiating and completing OAuth authorization flows
•Token Retrieval: Getting access tokens to call external APIs on behalf of users
•Token Refresh: Handling automatic or manual token refresh
•Credential Monitoring: Tracking credential status and handling revocations
•Custom OAuth Apps: Configuring your own OAuth app credentials for better branding
•API Key Storage: Securely storing API keys for services that don't support OAuth (see API Key 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:

Feature	Description
Token Storage	Encrypted storage of access tokens, refresh tokens, and API keys
Automatic Refresh	OAuth tokens are refreshed before expiry
Multi-tenant Isolation	Namespaces separate different users' credentials
Revocation Handling	Detects when users revoke OAuth access
Unified Interface	Same API for OAuth and API key credentials

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:

•Authenticates users through your own auth system
•Makes Interactor API calls on behalf of authenticated users
•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)

code

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   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:

Pattern	Namespace Value	Use Case
Per-user	`user_123`	Each user has their own credentials
Per-organization	`org_456`	Shared credentials within an organization
Shared/Global	`shared` or `default`	Company-wide credentials (e.g., shared Slack bot)
Account-level	(omit parameter)	Credentials accessible to all API calls

Namespace behavior:

javascript

// 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:

bash

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

Query Parameters:

Parameter	Type	Description
`namespace`	string	Filter by namespace (e.g., `user_123`)
`service_id`	string	Filter by service (e.g., `google_calendar`)
`status`	string	Filter by status: `active`, `expired`, `revoked`

Example - List credentials for a specific user:

bash

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

Response (structure inferred from credential object pattern):

json

{
  "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:

bash

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

Response:

json

{
  "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

bash

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

Response (structure inferred from credential object pattern):

json

{
  "data": {
    "id": "cred_abc",
    "service_id": "google_calendar",
    "service_name": "Google Calendar",
    "namespace": "user_123",
    "status": "active",
    "scopes": ["calendar.readonly", "calendar.events"],
    "metadata": {
      "email": "user@gmail.com"
    },
    "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.

bash

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

Response:

json

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

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

bash

# 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:

bash

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

Response (structure inferred):

json

{
  "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):

bash

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:

bash

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:

Parameter	Type	Required	Description
`service_id`	string	Yes	Service identifier (e.g., `google_calendar`, `slack`)
`namespace`	string	Yes	User namespace for data isolation (or omit for account-level)
`scopes`	array	No	OAuth scopes to request (defaults to service's default scopes)
`redirect_uri`	string	Yes	Where to redirect after authorization

Scope Validation & Mapping:

Interactor validates and maps scopes at different stages:

Stage	Validation
`/oauth/initiate`	Basic validation against service's known scopes
Authorization	Provider validates scopes; user may grant subset
Token exchange	Final granted scopes stored with credential

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

code

calendar.readonly  →  https://www.googleapis.com/auth/calendar.readonly
channels:read      →  https://api.slack.com/scopes/channels:read

If you request scopes not in the service catalog, you'll receive an invalid_scopes error at initiation time. If the user denies specific scopes during authorization, the credential will be created with only the granted scopes.

Response:

json

{
  "data": {
    "flow_id": "flow_xyz",
    "authorization_url": "https://accounts.google.com/o/oauth2/auth?client_id=...&redirect_uri=...&scope=...",
    "expires_at": "2026-01-20T12:15:00Z"
  }
}

Integration Flow

code

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   Your App      │     │   Interactor    │     │ External Service│
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         │ POST /oauth/initiate  │                       │
         │──────────────────────>│                       │
         │                       │                       │
         │ { authorization_url } │                       │
         │<──────────────────────│                       │
         │                       │                       │
         │ Redirect user ────────────────────────────────>
         │                       │                       │
         │                       │  User authorizes      │
         │                       │<──────────────────────│
         │                       │                       │
         │                       │  Callback with code   │
         │                       │<──────────────────────│
         │                       │                       │
         │                       │  Exchange for tokens  │
         │                       │──────────────────────>│
         │                       │                       │
         │ Redirect to your app  │                       │
         │<──────────────────────│                       │
         │                       │                       │
         │ GET /oauth/status     │                       │
         │──────────────────────>│                       │
         │                       │                       │
         │ { credential_id }     │                       │
         │<──────────────────────│                       │

Check OAuth Flow Status

Poll or check after redirect:

bash

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

Response:

json

{
  "data": {
    "flow_id": "flow_xyz",
    "status": "completed",
    "credential_id": "cred_abc"
  }
}

Status Values:

Status	Description
`pending`	User hasn't completed authorization yet
`completed`	Authorization successful, credential created
`failed`	Authorization failed (user denied or error)
`expired`	Flow expired (15 minutes timeout)

Complete OAuth Flow Implementation

Note: The implementations below use an InteractorClient class for HTTP requests. Configure this client per the interactor-auth skill, which handles JWT authentication and request signing for Interactor API calls.

TypeScript Implementation

typescript

import { InteractorClient } from './interactor-client';

export class CredentialManager {
  private client: InteractorClient;

  constructor(client: InteractorClient) {
    this.client = client;
  }

  /**
   * Start OAuth flow for a user to connect an external service.
   */
  async initiateOAuth(
    userId: string,
    serviceId: string,
    redirectUri: string,
    scopes?: string[]
  ): Promise<{ flowId: string; authorizationUrl: string }> {
    const result = await this.client.request<{
      flow_id: string;
      authorization_url: string;
    }>('POST', '/oauth/initiate', {
      service_id: serviceId,
      namespace: `user_${userId}`,
      redirect_uri: redirectUri,
      scopes
    });

    return {
      flowId: result.flow_id,
      authorizationUrl: result.authorization_url
    };
  }

  /**
   * Check OAuth flow status and get credential ID if completed.
   */
  async checkOAuthStatus(flowId: string): Promise<{
    status: 'pending' | 'completed' | 'failed' | 'expired';
    credentialId?: string;
    error?: string;
  }> {
    const result = await this.client.request<{
      status: string;
      credential_id?: string;
      error?: string;
    }>('GET', `/oauth/status/${flowId}`);

    return {
      status: result.status as any,
      credentialId: result.credential_id,
      error: result.error
    };
  }

  /**
   * Wait for OAuth flow to complete with polling.
   */
  async waitForOAuthCompletion(
    flowId: string,
    timeoutMs: number = 300000, // 5 minutes
    pollIntervalMs: number = 2000
  ): Promise<string> {
    const startTime = Date.now();

    while (Date.now() - startTime < timeoutMs) {
      const status = await this.checkOAuthStatus(flowId);

      if (status.status === 'completed' && status.credentialId) {
        return status.credentialId;
      }

      if (status.status === 'failed') {
        throw new Error(`OAuth failed: ${status.error || 'Unknown error'}`);
      }

      if (status.status === 'expired') {
        throw new Error('OAuth flow expired');
      }

      await new Promise(resolve => setTimeout(resolve, pollIntervalMs));
    }

    throw new Error('OAuth flow timed out');
  }

  /**
   * Get all credentials for a user.
   */
  async listUserCredentials(userId: string): Promise<Credential[]> {
    const result = await this.client.request<{
      credentials: Credential[];
    }>('GET', `/credentials?namespace=user_${userId}`);
    return result.credentials ?? [];
  }

  /**
   * Get access token to call external API.
   */
  async getAccessToken(credentialId: string): Promise<{
    accessToken: string;
    tokenType: string;
    expiresIn: number;
  }> {
    const result = await this.client.request<{
      access_token: string;
      token_type: string;
      expires_in: number;
    }>('GET', `/credentials/${credentialId}/token`);

    return {
      accessToken: result.access_token,
      tokenType: result.token_type,
      expiresIn: result.expires_in
    };
  }

  /**
   * Delete a credential.
   */
  async deleteCredential(credentialId: string): Promise<void> {
    await this.client.request('DELETE', `/credentials/${credentialId}`);
  }

  /**
   * Force refresh a credential's token.
   */
  async refreshCredential(credentialId: string): Promise<void> {
    await this.client.request('POST', `/credentials/${credentialId}/refresh`);
  }
}

interface Credential {
  id: string;
  service_id: string;
  service_name: string;
  namespace: string;
  status: 'pending' | 'active' | 'expired' | 'revoked';
  scopes: string[];
  metadata?: Record<string, string>;
  created_at: string;
  last_refreshed_at?: string;
  expires_at?: string;
}

Python Implementation

python

import time
from typing import Optional, List, Dict, Any
from dataclasses import dataclass

@dataclass
class Credential:
    id: str
    service_id: str
    service_name: str
    namespace: str
    status: str  # 'pending' | 'active' | 'expired' | 'revoked'
    scopes: List[str]
    created_at: str
    metadata: Optional[Dict[str, str]] = None
    last_refreshed_at: Optional[str] = None
    expires_at: Optional[str] = None

@dataclass
class OAuthStatus:
    status: str
    credential_id: Optional[str] = None
    error: Optional[str] = None

class CredentialManager:
    def __init__(self, client):
        self.client = client

    def initiate_oauth(
        self,
        user_id: str,
        service_id: str,
        redirect_uri: str,
        scopes: Optional[List[str]] = None
    ) -> Dict[str, str]:
        """Start OAuth flow for a user to connect an external service."""
        result = self.client.request('POST', '/oauth/initiate', {
            'service_id': service_id,
            'namespace': f'user_{user_id}',
            'redirect_uri': redirect_uri,
            'scopes': scopes
        })

        return {
            'flow_id': result['flow_id'],
            'authorization_url': result['authorization_url']
        }

    def check_oauth_status(self, flow_id: str) -> OAuthStatus:
        """Check OAuth flow status and get credential ID if completed."""
        result = self.client.request('GET', f'/oauth/status/{flow_id}')

        return OAuthStatus(
            status=result['status'],
            credential_id=result.get('credential_id'),
            error=result.get('error')
        )

    def wait_for_oauth_completion(
        self,
        flow_id: str,
        timeout_seconds: int = 300,
        poll_interval_seconds: int = 2
    ) -> str:
        """Wait for OAuth flow to complete with polling."""
        start_time = time.time()

        while time.time() - start_time < timeout_seconds:
            status = self.check_oauth_status(flow_id)

            if status.status == 'completed' and status.credential_id:
                return status.credential_id

            if status.status == 'failed':
                raise Exception(f'OAuth failed: {status.error or "Unknown error"}')

            if status.status == 'expired':
                raise Exception('OAuth flow expired')

            time.sleep(poll_interval_seconds)

        raise Exception('OAuth flow timed out')

    def list_user_credentials(self, user_id: str) -> List[Credential]:
        """Get all credentials for a user."""
        result = self.client.request('GET', f'/credentials?namespace=user_{user_id}')
        credentials_data = result.get('credentials', [])
        return [
            Credential(
                id=cred['id'],
                service_id=cred['service_id'],
                service_name=cred['service_name'],
                namespace=cred['namespace'],
                status=cred['status'],
                scopes=cred['scopes'],
                created_at=cred['created_at'],
                metadata=cred.get('metadata'),
                last_refreshed_at=cred.get('last_refreshed_at'),
                expires_at=cred.get('expires_at')
            )
            for cred in credentials_data
        ]

    def get_access_token(self, credential_id: str) -> Dict[str, Any]:
        """Get access token to call external API."""
        result = self.client.request('GET', f'/credentials/{credential_id}/token')
        return {
            'access_token': result['access_token'],
            'token_type': result['token_type'],
            'expires_in': result['expires_in']
        }

    def delete_credential(self, credential_id: str) -> None:
        """Delete a credential."""
        self.client.request('DELETE', f'/credentials/{credential_id}')

    def refresh_credential(self, credential_id: str) -> None:
        """Force refresh a credential's token."""
        self.client.request('POST', f'/credentials/{credential_id}/refresh')

Elixir Implementation

elixir

defmodule MyApp.Interactor.CredentialManager do
  @moduledoc """
  Manage OAuth credentials through Interactor.
  """

  alias MyApp.Interactor.Client

  @doc """
  Start OAuth flow for a user to connect an external service.
  """
  def initiate_oauth(user_id, service_id, redirect_uri, scopes \\ nil) do
    case Client.request(:post, "/oauth/initiate", %{
      service_id: service_id,
      namespace: "user_#{user_id}",
      redirect_uri: redirect_uri,
      scopes: scopes
    }) do
      {:ok, %{"flow_id" => flow_id, "authorization_url" => url}} ->
        {:ok, %{flow_id: flow_id, authorization_url: url}}

      {:error, reason} ->
        {:error, reason}
    end
  end

  @doc """
  Check OAuth flow status.
  """
  def check_oauth_status(flow_id) do
    case Client.request(:get, "/oauth/status/#{flow_id}") do
      {:ok, result} ->
        {:ok, %{
          status: result["status"],
          credential_id: result["credential_id"],
          error: result["error"]
        }}

      {:error, reason} ->
        {:error, reason}
    end
  end

  @doc """
  Wait for OAuth flow to complete with polling.
  """
  def wait_for_oauth_completion(flow_id, opts \\ []) do
    timeout_ms = Keyword.get(opts, :timeout_ms, 300_000)
    poll_interval_ms = Keyword.get(opts, :poll_interval_ms, 2_000)

    deadline = System.monotonic_time(:millisecond) + timeout_ms
    do_wait_for_completion(flow_id, deadline, poll_interval_ms)
  end

  defp do_wait_for_completion(flow_id, deadline, poll_interval_ms) do
    if System.monotonic_time(:millisecond) > deadline do
      {:error, :timeout}
    else
      case check_oauth_status(flow_id) do
        {:ok, %{status: "completed", credential_id: cred_id}} when not is_nil(cred_id) ->
          {:ok, cred_id}

        {:ok, %{status: "failed", error: error}} ->
          {:error, {:oauth_failed, error}}

        {:ok, %{status: "expired"}} ->
          {:error, :oauth_expired}

        {:ok, %{status: "pending"}} ->
          Process.sleep(poll_interval_ms)
          do_wait_for_completion(flow_id, deadline, poll_interval_ms)

        {:error, reason} ->
          {:error, reason}
      end
    end
  end

  @doc """
  List all credentials for a user.
  """
  def list_user_credentials(user_id) do
    case Client.request(:get, "/credentials?namespace=user_#{user_id}") do
      {:ok, %{"credentials" => credentials}} ->
        {:ok, credentials}

      {:ok, %{}} ->
        {:ok, []}

      {:error, reason} ->
        {:error, reason}
    end
  end

  @doc """
  Get access token for calling external API.
  """
  def get_access_token(credential_id) do
    case Client.request(:get, "/credentials/#{credential_id}/token") do
      {:ok, %{"access_token" => token, "token_type" => type, "expires_in" => expires}} ->
        {:ok, %{access_token: token, token_type: type, expires_in: expires}}

      {:error, reason} ->
        {:error, reason}
    end
  end

  @doc """
  Delete a credential.
  """
  def delete_credential(credential_id) do
    Client.request(:delete, "/credentials/#{credential_id}")
  end

  @doc """
  Force refresh a credential's token.
  """
  def refresh_credential(credential_id) do
    Client.request(:post, "/credentials/#{credential_id}/refresh")
  end
end

Production Recommendation: The waitForOAuthCompletion polling functions above are shown for simplicity. In production, prefer using webhooks to receive credential.created events instead of polling. Webhooks are more efficient and provide real-time notifications. See the interactor-webhooks skill for setup.

Timeout Note: OAuth flows expire after 15 minutes (expires_at in the initiate response). The example polling timeout of 5 minutes is intentionally shorter—if the user hasn't completed authorization within 5 minutes, they likely abandoned the flow. You can extend the polling timeout up to 15 minutes, but consider providing user feedback for long waits.

Custom OAuth Apps

By default, Interactor uses platform OAuth credentials. Configure your own for better branding and higher rate limits.

List OAuth Client Configs

bash

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

Create Custom OAuth Config

bash

curl -X POST https://core.interactor.com/api/v1/oauth-client-configs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "auth_provider": "google",
    "client_id": "your-google-client-id.apps.googleusercontent.com",
    "client_secret": "your-google-client-secret",
    "enabled": true
  }'

Supported Providers:

•google
•slack
•microsoft
•salesforce
•github
•dropbox

Get Config by Provider

bash

curl https://core.interactor.com/api/v1/oauth-client-configs/provider/google \
  -H "Authorization: Bearer <token>"

Update Config

bash

curl -X PUT https://core.interactor.com/api/v1/oauth-client-configs/config_123 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "client_secret": "new-client-secret"
  }'

Toggle Config (Enable/Disable)

bash

curl -X POST https://core.interactor.com/api/v1/oauth-client-configs/config_123/toggle \
  -H "Authorization: Bearer <token>"

Delete Config

bash

curl -X DELETE https://core.interactor.com/api/v1/oauth-client-configs/config_123 \
  -H "Authorization: Bearer <token>"

API Key Credentials (Non-OAuth)

Interactor can securely store API keys for services that don't support OAuth (e.g., SendGrid, Twilio, custom APIs).

Differences from OAuth Credentials

Aspect	OAuth Credentials	API Key Credentials
Creation	OAuth flow (`/oauth/initiate`)	Direct API call
Refresh lifecycle	Automatic token refresh	No refresh needed
Status values	`pending`, `active`, `expired`, `revoked`	`active` only (until deleted)
Token retrieval	`/credentials/{id}/token` returns access token	`/credentials/{id}/token` returns API key
Expiration	Token-based expiration	No expiration (unless service invalidates)

Store an API Key

bash

curl -X POST https://core.interactor.com/api/v1/credentials \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": "sendgrid",
    "namespace": "user_123",
    "auth_type": "api_key",
    "api_key": "SG.xxxxxxxxxxxx",
    "metadata": {
      "label": "Production SendGrid"
    }
  }'

Response (structure inferred):

json

{
  "data": {
    "id": "cred_xyz",
    "service_id": "sendgrid",
    "namespace": "user_123",
    "auth_type": "api_key",
    "status": "active",
    "metadata": {
      "label": "Production SendGrid"
    },
    "created_at": "2026-01-20T12:00:00Z"
  }
}

Retrieve an API Key

Use the same /token endpoint as OAuth credentials:

bash

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

Response:

json

{
  "data": {
    "access_token": "SG.xxxxxxxxxxxx",
    "token_type": "api_key"
  }
}

API Key Lifecycle

code

┌─────────────────┐
│     active      │──────────────────┐
└─────────────────┘                  │
        │                            │
        │ DELETE /credentials/{id}   │ Service invalidates key
        │                            │ (detected on use)
        ▼                            ▼
┌─────────────────┐          ┌─────────────────┐
│    (deleted)    │          │    (invalid)    │
└─────────────────┘          └─────────────────┘

Note: Unlike OAuth credentials, API keys don't have automatic status updates. If an external service invalidates a key, you'll discover this when the key fails. Consider implementing health checks for critical API key credentials.

Discovering Supported Services

Interactor maintains a catalog of supported services and their capabilities.

List Available Services

bash

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

Response (structure inferred):

json

{
  "data": {
    "services": [
      {
        "service_id": "google_calendar",
        "name": "Google Calendar",
        "auth_type": "oauth",
        "available_scopes": [
          "calendar.readonly",
          "calendar.events",
          "calendar.events.readonly"
        ],
        "default_scopes": ["calendar.readonly"]
      },
      {
        "service_id": "slack",
        "name": "Slack",
        "auth_type": "oauth",
        "available_scopes": [
          "channels:read",
          "chat:write",
          "users:read"
        ]
      },
      {
        "service_id": "sendgrid",
        "name": "SendGrid",
        "auth_type": "api_key",
        "available_scopes": null
      }
    ]
  }
}

Service Object Fields

Field	Type	Description
`service_id`	string	Unique identifier used in API calls
`name`	string	Human-readable service name
`auth_type`	string	`oauth` or `api_key`
`available_scopes`	array	Valid scopes for OAuth services (null for API key services)
`default_scopes`	array	Scopes requested if none specified

Tip: Cache the service catalog on your backend. It changes infrequently and caching reduces API calls during OAuth flow initiation.

Credential Status Lifecycle

code

                    ┌─────────────┐
                    │   pending   │
                    └──────┬──────┘
                           │ OAuth completes
                           ▼
                    ┌─────────────┐
           ┌───────>│   active    │<──────┐
           │        └──────┬──────┘       │
           │               │              │
   refresh │    token      │    user      │ re-authorize
  succeeds │   expires     │   revokes    │
           │               │              │
           │        ┌──────┴──────┐       │
           └────────│   expired   │       │
                    └─────────────┘       │
                           │              │
                           ▼              │
                    ┌─────────────┐       │
                    │   revoked   │───────┘
                    └─────────────┘

Status Descriptions

Status	Description	Action
`pending`	OAuth flow initiated but not completed	Wait for user to complete authorization
`active`	Token valid and working	Use normally
`expired`	Token expired and refresh failed	Re-initiate OAuth flow
`revoked`	User revoked access in external service	Re-initiate OAuth flow

Error Handling

Credential-Specific Errors

Error Code	HTTP Status	Description	Resolution
`credential_not_found`	404	Credential doesn't exist	Check credential ID
`credential_expired`	400	OAuth token expired and refresh failed	Re-initiate OAuth flow
`credential_revoked`	400	User revoked access	Re-initiate OAuth flow
`invalid_scopes`	400	Requested scopes not available	Check service documentation
`oauth_flow_expired`	400	OAuth flow timed out (15 min)	Start new OAuth flow
`oauth_flow_not_found`	404	Flow ID doesn't exist	Start new OAuth flow

Error Handling Example

typescript

async function getExternalApiToken(credentialId: string): Promise<string> {
  try {
    const { accessToken } = await credentialManager.getAccessToken(credentialId);
    return accessToken;
  } catch (error: any) {
    const code = error.response?.data?.error?.code;

    switch (code) {
      case 'credential_expired':
      case 'credential_revoked':
        // Token is no longer valid, need to re-authorize
        throw new ReauthorizationRequiredError(
          'Please reconnect your account',
          credentialId
        );

      case 'credential_not_found':
        throw new CredentialNotFoundError(
          'Credential not found',
          credentialId
        );

      default:
        throw error;
    }
  }
}

Webhook Events

Subscribe to credential events for real-time updates:

Event	Description	When Triggered
`credential.created`	New credential created	OAuth flow completed
`credential.refreshed`	Token successfully refreshed	Automatic or manual refresh
`credential.expired`	Token expired (refresh failed)	Refresh token invalid
`credential.revoked`	User revoked access	User revoked in external service

See interactor-webhooks skill for webhook setup.

Webhook Payload Example

json

{
  "id": "evt_abc123",
  "type": "credential.expired",
  "timestamp": "2026-01-20T12:00:00Z",
  "data": {
    "credential_id": "cred_abc",
    "service_id": "google_calendar",
    "namespace": "user_123",
    "reason": "refresh_token_invalid"
  }
}

Security Considerations

Concern	Recommendation
Token Logging	Never log access tokens - they grant access to user data in external services
Namespace Isolation	Each user MUST have a unique namespace (e.g., `user_{id}`) to prevent cross-user access
Credential ID Exposure	Treat credential IDs as sensitive; avoid exposing them in client-side code or URLs
Webhook Verification	Always verify webhook signatures before processing credential events
Scope Minimization	Request only the OAuth scopes your application actually needs
Token Storage	Let Interactor handle token storage; never store access/refresh tokens in your own database
Error Messages	Don't expose credential details in error messages shown to users

Rate Limits & Token Caching

API Rate Limits

Interactor applies rate limits to protect service stability. Monitor these headers in API responses:

Header	Description
`X-RateLimit-Limit`	Maximum requests per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Rate limit categories:

Category	Typical Limit	Endpoints
Credential reads	High	`GET /credentials`, `GET /credentials/{id}`
Token retrieval	High	`GET /credentials/{id}/token`
OAuth flows	Moderate	`POST /oauth/initiate`, `GET /oauth/status`
Credential writes	Lower	`POST /credentials`, `DELETE /credentials/{id}`

Handling Rate Limits

When you receive a 429 Too Many Requests response:

typescript

async function requestWithRetry(fn: () => Promise<Response>, maxRetries = 3): Promise<Response> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fn();

    if (response.status === 429) {
      const resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0');
      const waitMs = Math.max(1000, (resetTime * 1000) - Date.now());

      // Exponential backoff with jitter
      const backoff = Math.min(waitMs, 1000 * Math.pow(2, attempt) + Math.random() * 1000);
      await new Promise(resolve => setTimeout(resolve, backoff));
      continue;
    }

    return response;
  }
  throw new Error('Rate limit exceeded after retries');
}

Token Caching Strategy

The /credentials/{id}/token endpoint automatically refreshes expired tokens, but caching reduces API calls:

typescript

interface CachedToken {
  accessToken: string;
  expiresAt: number; // Unix timestamp
}

const tokenCache = new Map<string, CachedToken>();

async function getToken(credentialId: string): Promise<string> {
  const cached = tokenCache.get(credentialId);

  // Use cached token if valid for at least 5 more minutes
  if (cached && cached.expiresAt > Date.now() + 5 * 60 * 1000) {
    return cached.accessToken;
  }

  // Fetch fresh token
  const { accessToken, expiresIn } = await credentialManager.getAccessToken(credentialId);

  tokenCache.set(credentialId, {
    accessToken,
    expiresAt: Date.now() + (expiresIn * 1000)
  });

  return accessToken;
}

Recommended cache TTLs:

Data	Cache Duration	Reason
Access tokens	`expires_in - 5 minutes`	Buffer for refresh
Service catalog	24 hours	Changes infrequently
Credential metadata	5-15 minutes	May change (scopes, status)

Best Practices

DO

•Use namespaces per user - Isolate each user's credentials with user_{id} namespace
•Handle revocation gracefully - Prompt users to re-authorize when credentials are revoked
•Request minimal scopes - Only request the OAuth permissions you actually need
•Use custom OAuth apps for production - Provides better branding and higher rate limits
•Monitor credential health - Subscribe to webhook events for proactive handling
•Cache tokens appropriately - The /token endpoint handles refresh, but cache to reduce calls

DON'T

•Don't store external tokens in your database - Let Interactor handle secure storage
•Don't ignore credential status - Always check status before assuming tokens are valid
•Don't request excessive scopes - Users are less likely to authorize broad permissions
•Don't poll excessively - Use webhooks instead of polling for status changes

Troubleshooting

OAuth flow returns `expired` immediately

•OAuth flow URLs expire after 15 minutes
•Ensure the user completes authorization promptly after redirect
•If users consistently timeout, consider UX improvements to guide them faster

Token refresh keeps failing

•Check if the user revoked access in the external service's settings
•Verify your OAuth app credentials (client_id/client_secret) are still valid
•For custom OAuth apps, ensure the refresh token hasn't been invalidated

`invalid_scopes` error

•The external service may have deprecated or renamed scopes
•Check the provider's current OAuth documentation for valid scope names
•Some scopes require app verification (e.g., Google sensitive scopes)

`credential_not_found` after successful OAuth

•Ensure you're using the correct credential_id from the OAuth flow completion
•Check that the namespace matches what was used during initiation
•Verify the credential wasn't deleted by another process

Webhook events not being received

•Verify your webhook endpoint is publicly accessible
•Check that you've subscribed to credential events (see interactor-webhooks skill)
•Ensure webhook signature verification isn't rejecting valid requests

External API returns 401 despite valid credential

•The access token may have just expired; call /credentials/{id}/token to get a fresh one
•Some services require re-authorization after certain account changes
•Check if the user's account in the external service is still active

Common Services and Scopes

Note: The scope names shown below are Interactor's simplified identifiers. Interactor automatically maps these to the provider's full OAuth scope URLs (e.g., calendar.readonly → https://www.googleapis.com/auth/calendar.readonly). Refer to each provider's OAuth documentation for the complete list of available scopes.

Google Calendar

javascript

{
  service_id: "google_calendar",
  scopes: [
    "calendar.readonly",      // Read calendars
    "calendar.events",        // Read/write events
    "calendar.events.readonly" // Read events only
  ]
}

Google Drive

javascript

{
  service_id: "google_drive",
  scopes: [
    "drive.readonly",         // Read all files
    "drive.file",             // Access files created by app
    "drive.metadata.readonly" // Read file metadata
  ]
}

Slack

javascript

{
  service_id: "slack",
  scopes: [
    "channels:read",          // View channels
    "chat:write",             // Send messages
    "users:read",             // View users
    "files:read"              // Access files
  ]
}

Microsoft 365

javascript

{
  service_id: "microsoft",
  scopes: [
    "Calendars.Read",         // Read calendars
    "Mail.Read",              // Read email
    "Files.Read",             // Read OneDrive files
    "User.Read"               // Read user profile
  ]
}

Output Format

When implementing credential management, provide this summary:

markdown

## Credential Management Implementation Report

**Date**: YYYY-MM-DD
**User/Namespace**: user_123

### OAuth Flow Status
| Step | Status |
|------|--------|
| Initiate OAuth | ✓ Completed |
| User Authorization | ✓ Completed |
| Token Exchange | ✓ Completed |
| Credential Created | ✓ cred_abc |

### Connected Services
| Service | Status | Scopes |
|---------|--------|--------|
| Google Calendar | Active | calendar.readonly, calendar.events |
| Slack | Active | channels:read, chat:write |

### Implementation Checklist
- [ ] OAuth flow initiation endpoint
- [ ] OAuth callback handling
- [ ] Token retrieval for API calls
- [ ] Credential status monitoring
- [ ] Webhook handlers for credential events
- [ ] Re-authorization flow for expired/revoked credentials

### Next Steps
1. Use credentials with AI agents (see `interactor-agents` skill)
2. Set up credential webhooks (see `interactor-webhooks` skill)

Related Skills

•interactor-auth: Setup authentication (prerequisite)
•interactor-agents: AI agents can use credentials to access external services
•interactor-workflows: Automate tasks using stored credentials
•interactor-webhooks: Get notified of credential status changes

Interactor Credential Management Skill

When to Use

When NOT to Use

Prerequisites

Overview

Architecture Concepts

Backend-Only Execution Model

Namespace Patterns

Credential Access Control

Instructions

Step 1: List All Credentials

Step 2: Get Credentials Summary

Step 3: Get a Specific Credential

Step 4: Get Access Token for External API

Step 5: Force Token Refresh

Step 6: Delete a Credential

OAuth Flow Implementation

Initiate OAuth Authorization

Integration Flow

Check OAuth Flow Status

Complete OAuth Flow Implementation

TypeScript Implementation

Python Implementation

Elixir Implementation

Custom OAuth Apps

List OAuth Client Configs

Create Custom OAuth Config

Get Config by Provider

Update Config

Toggle Config (Enable/Disable)

Delete Config

API Key Credentials (Non-OAuth)

Differences from OAuth Credentials

Store an API Key

Retrieve an API Key

API Key Lifecycle

Discovering Supported Services

List Available Services

Service Object Fields

Credential Status Lifecycle

Status Descriptions

Error Handling

Credential-Specific Errors

Error Handling Example

Webhook Events

Webhook Payload Example

Security Considerations

Rate Limits & Token Caching

API Rate Limits

Handling Rate Limits

Token Caching Strategy

Best Practices

DO

DON'T

Troubleshooting

OAuth flow returns expired immediately

Token refresh keeps failing

invalid_scopes error

credential_not_found after successful OAuth

Webhook events not being received

External API returns 401 despite valid credential

Common Services and Scopes

Google Calendar

Google Drive

Slack

Microsoft 365

Output Format

Related Skills

OAuth flow returns `expired` immediately

`invalid_scopes` error

`credential_not_found` after successful OAuth