Initial commit

skills/protocolsio-integration/references/authentication.md

@@ -0,0 +1,100 @@
+# Protocols.io Authentication
+
+## Overview
+
+The protocols.io API supports two types of access tokens for authentication, enabling access to both public and private content.
+
+## Access Token Types
+
+### 1. CLIENT_ACCESS_TOKEN
+
+- **Purpose**: Enables access to public content and the private content of the client user
+- **Use case**: When accessing your own protocols and public protocols
+- **Scope**: Limited to the token owner's private content plus all public content
+
+### 2. OAUTH_ACCESS_TOKEN
+
+- **Purpose**: Grants access to specific users' private content plus all public content
+- **Use case**: When building applications that need to access other users' content with their permission
+- **Scope**: Full access to authorized user's private content plus all public content
+
+## Authentication Header
+
+All API requests must include an Authorization header:
+
+```
+Authorization: Bearer [ACCESS_TOKEN]
+```
+
+## OAuth Flow
+
+### Step 1: Generate Authorization Link
+
+Direct users to the authorization URL to grant access:
+
+```
+GET https://protocols.io/api/v3/oauth/authorize
+```
+
+**Parameters:**
+- `client_id` (required): Your application's client ID
+- `redirect_uri` (required): URL to redirect users after authorization
+- `response_type` (required): Set to "code"
+- `state` (optional but recommended): Random string to prevent CSRF attacks
+
+**Example:**
+```
+https://protocols.io/api/v3/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&state=RANDOM_STRING
+```
+
+### Step 2: Exchange Authorization Code for Token
+
+After user authorization, protocols.io redirects to your `redirect_uri` with an authorization code. Exchange this code for an access token:
+
+```
+POST https://protocols.io/api/v3/oauth/token
+```
+
+**Parameters:**
+- `grant_type`: Set to "authorization_code"
+- `code`: The authorization code received
+- `client_id`: Your application's client ID
+- `client_secret`: Your application's client secret
+- `redirect_uri`: Must match the redirect_uri used in Step 1
+
+**Response includes:**
+- `access_token`: The OAuth access token to use for API requests
+- `token_type`: "Bearer"
+- `expires_in`: Token lifetime in seconds (typically 1 year)
+- `refresh_token`: Token for refreshing the access token
+
+### Step 3: Refresh Access Token
+
+Before the access token expires (typically 1 year), use the refresh token to obtain a new access token:
+
+```
+POST https://protocols.io/api/v3/oauth/token
+```
+
+**Parameters:**
+- `grant_type`: Set to "refresh_token"
+- `refresh_token`: The refresh token received in Step 2
+- `client_id`: Your application's client ID
+- `client_secret`: Your application's client secret
+
+## Rate Limits
+
+Be aware of rate limiting when making API requests:
+
+- **Standard endpoints**: 100 requests per minute per user
+- **PDF endpoint** (`/view/[protocol-uri].pdf`):
+  - Signed-in users: 5 requests per minute
+  - Unsigned users: 3 requests per minute
+
+## Best Practices
+
+1. **Store tokens securely**: Never expose access tokens in client-side code or version control
+2. **Handle token expiration**: Implement automatic token refresh before expiration
+3. **Respect rate limits**: Implement exponential backoff for rate limit errors
+4. **Use state parameter**: Always include a state parameter in OAuth flow for security
+5. **Validate redirect_uri**: Ensure redirect URIs match exactly between authorization and token requests