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

> Learn to set up OAuth authentication for Protocols.io API integration using the Authorization Code grant flow. Securely authenticate your applications and access API resources.

- Repository: [K-Dense/scientific-agent-skills](https://github.com/K-Dense-AI/scientific-agent-skills)
- Tags: how-to-guide
- Published: 2026-05-14

---

**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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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.

```python
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`.

```python
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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/protocols_api.md) reference file confirms that protected endpoints require `Authorization: Bearer <token>`.

```python
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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/scientific-skills/protocolsio-integration/SKILL.md) and [`docs/scientific-skills.md`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/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`](https://github.com/K-Dense-AI/scientific-agent-skills/blob/main/protocols_api.md) reference file details which endpoints require authentication.