API Authentication

The Knapsack API uses the OAuth 2.0 Client Credentials Flow for server-to-server authentication. This is the industry-standard approach used by major APIs like Microsoft Graph, Google Cloud, and AWS.

Overview

Authentication works in two steps:

1. Get API Credentials: Organization admins create API clients in the Admin Console to receive a Client ID and Client Secret
2. Get Access Token: Exchange your Client ID and Secret for an access token to use with API requests

Getting API Credentials

Only organization admins can create API clients:

1. Navigate to the Admin Console in your Knapsack account
2. Go to the "API Clients" section
3. Click "Create New API Client"
4. Provide a name and description for your client
5. Save your Client ID and Client Secret securely - the secret is only shown once

⚠️ Important: Store your Client Secret securely. It will only be displayed once upon creation. If you lose it, you'll need to regenerate a new secret.

Getting an Access Token

Request

Exchange your credentials for an access token:

curl -X POST https://api.knapsack.ai/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGVzdF9yZWZyZXNoX3Rva2VuXzEyMzQ1...",
  "scope": "read:knaps write:knaps"
}

Using the Access Token

Include the access token in the Authorization header of your API requests:

curl -X GET https://api.knapsack.ai/api/studio/knap-tools \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Token Expiration and Refresh

Access tokens expire after 1 hour (3600 seconds). When a token expires, you have two options:

Option 1: Request a New Token

Simply repeat the token request with your Client ID and Secret:

curl -X POST https://api.knapsack.ai/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Option 2: Use the Refresh Token

Use your refresh token to get a new access token without sending your Client Secret:

curl -X POST https://api.knapsack.ai/api/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Refresh tokens expire after 30 days. After that, you'll need to request a new token using Option 1.

Security Best Practices

Protect Your Credentials

• Never commit credentials to version control
• Store Client ID and Secret in environment variables or secure credential stores
• Use different API clients for development and production environments
• Rotate secrets regularly

Example: Using Environment Variables

# .env file (add to .gitignore)
KNAPSACK_CLIENT_ID=kn_abc123...
KNAPSACK_CLIENT_SECRET=kn_secret_xyz789...

# Python example
import os
import requests

client_id = os.environ['KNAPSACK_CLIENT_ID']
client_secret = os.environ['KNAPSACK_CLIENT_SECRET']

response = requests.post(
    'https://api.knapsack.ai/api/oauth/token',
    data={
        'grant_type': 'client_credentials',
        'client_id': client_id,
        'client_secret': client_secret
    }
)

token_data = response.json()
access_token = token_data['access_token']

# Use the access token
headers = {'Authorization': f'Bearer {access_token}'}
knaps = requests.get(
    'https://api.knapsack.ai/api/studio/knap-tools',
    headers=headers
)

Managing API Clients

Organization admins can manage API clients in the Admin Console:

• View all API clients for your organization
• See last used timestamp to identify inactive clients
• Regenerate secrets if a secret is compromised
• Revoke clients to immediately invalidate all tokens

When you revoke a client or regenerate its secret:

• All existing access tokens are immediately invalidated
• All refresh tokens are immediately invalidated
• API requests using those tokens will receive a 401 Unauthorized response

Error Responses

401 Unauthorized

Invalid or expired credentials/tokens:

{
  "detail": "Invalid client credentials"
}

{
  "detail": "API client has been revoked"
}

400 Bad Request

Invalid request format:

{
  "detail": "Unsupported grant_type. Must be 'client_credentials' or 'refresh_token'"
}

Rate Limiting

API clients are subject to rate limiting (default: 100 requests per minute). Rate limits are configurable per client in the Admin Console.

When you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Organization-Level Access

API clients have access to all resources within their organization, including:

• Organization Knaps
• Shared workflows
• Organization data and configurations

API clients do not have access to:

• Individual user's private Knaps
• Other organizations' resources
• User-level settings and preferences