Connect with ContextFile
Build applications that integrate with ContextFile.ai using OAuth 2.0. Allow users to securely authorize your app to access their context files, skills, and tasks.
Why Use OAuth 2.0?
OAuth 2.0 is the industry standard for secure authorization. It allows users to grant your application access to their ContextFile.ai data without sharing their credentials.
How OAuth Works
1User Clicks "Connect with ContextFile"
Your app redirects the user to our authorization URL with your client_id and requested scopes.
2User Reviews & Approves
The user sees your app name, logo, and the permissions you're requesting. They click "Allow" to grant access.
3Exchange Code for Tokens
We redirect back to your app with an authorization code. Your server exchanges this for access and refresh tokens.
4Make API Requests
Use the access token to call our API on behalf of the user. When it expires, use the refresh token to get a new one.
Creating an OAuth App
Step 1: Register Your Application
Go to Developer → OAuth Apps in your dashboard. Click "Register New App" and fill in your app details including name, logo, and redirect URIs.
Step 2: Save Your Credentials
Important: Copy your Client ID and Client Secret immediately. The secret is only shown once. Store it securely in your application's environment variables.
Step 3: Configure Redirect URIs
Add all redirect URIs where users will be sent after authorization. For development, you can use http://localhost:3000/callback.
The Connect Button
Add a "Connect with ContextFile" button to your application. We provide a React component, or you can build your own using the authorization URL.
Default (Gradient)
Outline
Text Only
Sizes
import { ConnectWithContextFile } from '@contextfile/react'
// In your component
<ConnectWithContextFile
clientId="YOUR_CLIENT_ID"
redirectUri="https://yourapp.com/callback"
scope="profile:read contexts:read"
state={generateCSRFToken()}
/>Or build the URL manually:
https://contextfile.ai/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=YOUR_CALLBACK_URL
&scope=profile:read+contexts:read
&state=RANDOM_STATEOAuth Endpoints
/oauth/authorizeAuthorization endpoint (user consent)/api/oauth/tokenExchange code for tokens/api/oauth/revokeRevoke a token/api/oauth/introspectInspect token validityAvailable Scopes
Request only the scopes your application needs. Requesting fewer scopes increases user trust.
profile:readView basic profile informationcontexts:readView context files and their contentscontexts:writeCreate, update, and delete context filesskills:readView skills and their configurationsskills:executeRun skills to generate contenttasks:readView tasks and workflowstasks:executeRun tasks and workflowstasks:writeCreate, update, and delete tasksExample Implementation
Step 1: Redirect to Authorization
const authUrl = new URL('https://contextfile.ai/oauth/authorize');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('client_id', 'YOUR_CLIENT_ID');
authUrl.searchParams.set('redirect_uri', 'https://yourapp.com/callback');
authUrl.searchParams.set('scope', 'profile:read contexts:read');
authUrl.searchParams.set('state', generateRandomState());
// Redirect user
window.location.href = authUrl.toString();Step 2: Exchange Code for Tokens
// In your callback handler (server-side)
const response = await fetch('https://contextfile.ai/api/oauth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams({
grant_type: 'authorization_code',
code: authorizationCode,
redirect_uri: 'https://yourapp.com/callback',
client_id: process.env.CONTEXTFILE_CLIENT_ID,
client_secret: process.env.CONTEXTFILE_CLIENT_SECRET,
}),
});
const tokens = await response.json();
// { access_token, refresh_token, expires_in, token_type, scope }Step 3: Make API Requests
const response = await fetch('https://contextfile.ai/api/v1/contexts', {
headers: {
'Authorization': `Bearer ${accessToken}`,
'Content-Type': 'application/json',
},
});
const contexts = await response.json();Refreshing Tokens
const response = await fetch('https://contextfile.ai/api/oauth/token', {
method: 'POST',
headers: {
'Content-Type': 'application/x-www-form-urlencoded',
},
body: new URLSearchParams({
grant_type: 'refresh_token',
refresh_token: storedRefreshToken,
client_id: process.env.CONTEXTFILE_CLIENT_ID,
client_secret: process.env.CONTEXTFILE_CLIENT_SECRET,
}),
});
const newTokens = await response.json();Token Lifetimes
Access Token
Valid for 1 hour. Use this token for API requests. When it expires, use your refresh token to get a new one.
Refresh Token
Valid for 30 days. Store securely. Each refresh returns a new refresh token (rotation for security).
Security Best Practices
Use PKCE
Always use PKCE (Proof Key for Code Exchange) for public clients like SPAs and mobile apps to prevent authorization code interception.
Validate State
Always generate and validate the state parameter to prevent CSRF attacks on your callback endpoint.
Secure Token Storage
Store tokens securely. Never expose them in URLs, localStorage (for sensitive apps), or client-side code.
Minimal Scopes
Request only the scopes your app actually needs. This increases user trust and limits potential damage if tokens are compromised.
OAuth Integration Tips
- Always use PKCE (Proof Key for Code Exchange) for public clients like mobile apps
- Store tokens securely - never in localStorage for sensitive apps
- Request only the scopes your application actually needs
- Implement token refresh logic to maintain seamless user experience
- Use the state parameter to prevent CSRF attacks
- Handle token expiration gracefully with automatic refresh