How to Set Up OAuth Authentication for Protocols.io API Integration: A Complete Guide

The Protocols.io API integration requires OAuth 2.0 Authorization Code grant flow: register an application to obtain credentials, redirect users to https://protocols.io/api/v3/oauth/authorize, capture the authorization code, and exchange it at https://protocols.io/api/v3/oauth/token for an access token.

According to the K-Dense-AI/scientific-agent-skills repository, the Protocols.io platform protects private protocols through standard OAuth 2.0. The integration documentation in scientific-skills/protocolsio-integration/references/authentication.md outlines the exact endpoints and payload requirements needed to authenticate scientific-agent skills.

OAuth 2.0 Authorization Code Flow Overview

The Protocols.io API integration implements the standard Authorization Code grant type. This flow separates user authentication from application authorization, keeping client secrets secure while allowing users to grant permissions through a browser-based consent screen.

The process involves two primary endpoints:

• https://protocols.io/api/v3/oauth/authorize – A GET endpoint that initiates user authorization and returns a temporary authorization code to your redirect_uri.
• https://protocols.io/api/v3/oauth/token – A POST endpoint that exchanges the authorization code for a long-lived access token.

As documented in scientific-skills/protocolsio-integration/references/authentication.md, you must complete both steps before making authenticated API requests to private protocol data.

Prerequisites and Required Credentials

Before implementing the OAuth flow, gather three critical components from the Protocols.io developer portal:

1. Client ID – A public identifier for your application.
2. Client Secret – A confidential key used only in server-to-server token exchange requests.
3. Redirect URI – A secure HTTPS endpoint under your control where Protocols.io returns the authorization code.

Store these credentials in environment variables or a secure vault. Never commit CLIENT_ID or CLIENT_SECRET to version control, as noted in the repository's SKILL.md documentation for the protocolsio-integration skill.

Step-by-Step Implementation

Step 1: Register Your Application

Create a new application in the Protocols.io developer settings. Navigate to Developer Settings → Create New Application and specify your production redirect_uri. After registration, the portal issues a Client ID and Client Secret pair.

Step 2: Build the Authorization URL

Construct the authorization URL with required query parameters to send the user to Protocols.io for consent. Include a state parameter containing a cryptographically secure random string to prevent CSRF attacks.

import os
import secrets
from urllib.parse import urlencode

CLIENT_ID = os.getenv("PROTOCOLS_CLIENT_ID")
REDIRECT_URI = "https://myapp.example.com/protocols/callback"
STATE = secrets.token_urlsafe(16)  # Store this in user session for verification

params = {
    "client_id": CLIENT_ID,
    "redirect_uri": REDIRECT_URI,
    "response_type": "code",
    "state": STATE,
}
auth_url = f"https://protocols.io/api/v3/oauth/authorize?{urlencode(params)}"

Redirect the user's browser to auth_url. Protocols.io will authenticate the user, request consent for the requested scopes, and redirect back to your specified redirect_uri with ?code=AUTH_CODE&state=STATE appended.

Step 3: Handle the Callback and Exchange Code for Token

In your callback handler, verify that the returned state matches the value stored in the user's session. Then exchange the authorization code for an access token by sending a POST request to the token endpoint with grant_type=authorization_code.

import requests

def exchange_code_for_token(code: str) -> dict:
    token_endpoint = "https://protocols.io/api/v3/oauth/token"
    data = {
        "grant_type": "authorization_code",
        "code": code,
        "redirect_uri": REDIRECT_URI,
        "client_id": CLIENT_ID,
        "client_secret": os.getenv("PROTOCOLS_CLIENT_SECRET"),
    }
    resp = requests.post(token_endpoint, data=data)
    resp.raise_for_status()
    return resp.json()  # Contains access_token, token_type, expires_in, refresh_token

The JSON response includes access_token, token_type (Bearer), expires_in (seconds until expiration), and optionally a refresh_token for obtaining new access tokens without repeating the full flow.

Step 4: Use the Access Token in API Requests

Include the access token in the Authorization header for all subsequent Protocols.io API calls. The protocols_api.md reference file confirms that protected endpoints require Authorization: Bearer <token>.

def protocols_api_get(path: str, token: str):
    base = "https://protocols.io/api/v3"
    headers = {"Authorization": f"Bearer {token}"}
    return requests.get(f"{base}/{path}", headers=headers).json()

# Example: Fetch user profile

profile = protocols_api_get("profile", token_data["access_token"])

Security Best Practices

When implementing OAuth for the Protocols.io API integration, follow these security measures from the scientific-skills/protocolsio-integration/references/authentication.md documentation:

• Validate state tokens strictly in callback handlers to prevent CSRF attacks.
• Use HTTPS only for redirect URIs; the OAuth 2.0 specification forbids HTTP callbacks in production.
• Store tokens encrypted at rest if persisting them for background job processing.
• Implement token refresh logic before expiration using the refresh_token grant type when available.

Summary

• The Protocols.io API integration uses standard OAuth 2.0 Authorization Code flow with endpoints at /oauth/authorize and /oauth/token.
• You must register an application in the Protocols.io developer portal to obtain CLIENT_ID and CLIENT_SECRET.
• Always generate and verify a state parameter to mitigate CSRF vulnerabilities during the authorization callback.
• Exchange the temporary authorization code for a Bearer token via POST request, then use it in Authorization: Bearer <token> headers for all API calls.

Frequently Asked Questions

What OAuth grant type does the Protocols.io API integration use?

The integration uses the Authorization Code grant type. As documented in scientific-skills/protocolsio-integration/references/authentication.md, this requires redirecting users to the authorization endpoint, receiving a code via callback, and exchanging that code server-side for an access token. This flow keeps the client secret confidential while allowing users to consent to specific permissions.

How do I handle token expiration in long-running scientific-agent skills?

Monitor the expires_in field in the token exchange response. Before expiration, use the refresh token (if provided) to request a new access token by sending a POST to /oauth/token with grant_type=refresh_token. If no refresh token is available, you must re-initiate the full Authorization Code flow. Store tokens securely and implement background refresh logic to avoid service interruptions.

Where are the OAuth endpoints documented in the repository?

The primary documentation lives in scientific-skills/protocolsio-integration/references/authentication.md, which specifies the exact URLs (https://protocols.io/api/v3/oauth/authorize and https://protocols.io/api/v3/oauth/token) and required parameters. Additional context appears in scientific-skills/protocolsio-integration/SKILL.md and docs/scientific-skills.md regarding when to apply this authentication within the broader scientific-agent framework.

Can I use the Protocols.io API without OAuth for public protocols?

Publicly accessible protocols may not require OAuth authentication, but any operation involving private protocols, user profiles, or write operations (create, update, publish) requires a valid Bearer token obtained through the OAuth flow described above. The protocols_api.md reference file details which endpoints require authentication.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}