101 lines
3.3 KiB
Markdown
101 lines
3.3 KiB
Markdown
# 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
|