Appearance
Authorization Code Flow
The authorization code flow is the recommended OAuth 2.0 flow for web applications that need to act on behalf of a user. It uses PKCE (Proof Key for Code Exchange) for added security.
Flow Overview
Step 1: Generate PKCE Parameters
javascript
// Generate a random code verifier
const codeVerifier = crypto.randomUUID() + crypto.randomUUID();
// Create the code challenge (S256)
const encoder = new TextEncoder();
const data = encoder.encode(codeVerifier);
const digest = await crypto.subtle.digest('SHA-256', data);
const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');Step 2: Redirect to Authorization Endpoint
GET /oauth/auth?
response_type=code&
client_id=YOUR_CLIENT_ID&
redirect_uri=https://yourapp.com/callback&
scope=openid profile projects:read&
code_challenge=CODE_CHALLENGE&
code_challenge_method=S256&
resource=https://developer.knowify.com/api&
state=RANDOM_STATE| Parameter | Required | Description |
|---|---|---|
response_type | Yes | Must be code |
client_id | Yes | Your OAuth client ID |
redirect_uri | Yes | Must match a registered redirect URI |
scope | Yes | Space-separated list of scopes |
code_challenge | Yes | PKCE challenge (S256) |
code_challenge_method | Yes | Must be S256 |
state | Recommended | Random string to prevent CSRF |
resource | Recommended | Audience for the access token (RFC 8707). Use https://developer.knowify.com/api for the REST API — portal-registered clients default to it |
Step 3: Exchange Code for Tokens
After the user approves, they're redirected to your redirect_uri with a code parameter:
bash
curl -X POST /oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=AUTH_CODE" \
-d "redirect_uri=https://yourapp.com/callback" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "code_verifier=YOUR_CODE_VERIFIER" \
-d "resource=https://developer.knowify.com/api"Response:
json
{
"access_token": "eyJhbG...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "ey...",
"scope": "openid profile projects:read"
}The access token's aud claim must be https://developer.knowify.com/api — the API rejects tokens issued for any other audience (e.g. an MCP server) with a 401 telling you which resource to request. Requesting a resource your client isn't allowed returns invalid_target.
Step 4: Use the Access Token
bash
curl -H "Authorization: Bearer ACCESS_TOKEN" \
https://developer.knowify.com/api/projectsRefreshing Tokens
When the access token expires, use the refresh token:
bash
curl -X POST /oauth/token \
-d "grant_type=refresh_token" \
-d "refresh_token=REFRESH_TOKEN" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "resource=https://developer.knowify.com/api"