Skip to main content
Every request to the Knowledge Stack API must include a valid token in the Authorization header: 
Authorization: Bearer <your-token>
There are three ways to get a token: API keys, password sign-in, and SSO.

​
API keys

API keys are the recommended method for server-to-server integrations. They don’t expire unless you delete them.

​
Create an API key

curl -X POST https://api-staging.knowledgestack.ai/v1/api-keys \
  -H "Authorization: Bearer <your-existing-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-service-key"
  }'
The response includes the key value. Store it immediately — the full key is only returned once. 
{
  "id": "key_01j...",
  "name": "my-service-key",
  "key": "ks_live_...",
  "created_at": "2025-01-15T10:00:00Z"
}

​
Use an API key

Pass the key as a Bearer token on every request: 
curl https://api-staging.knowledgestack.ai/v1/documents \
  -H "Authorization: Bearer ks_live_..."

​
Manage your keys

List all API keys: 
curl https://api-staging.knowledgestack.ai/v1/api-keys \
  -H "Authorization: Bearer <your-token>"
Delete a key when it’s no longer needed: 
curl -X DELETE https://api-staging.knowledgestack.ai/v1/api-keys/<api_key_id> \
  -H "Authorization: Bearer <your-token>"
Deleting an API key immediately invalidates it. Any service using that key will start receiving 401 errors.

​
Password sign-in

If your users authenticate directly against Knowledge Stack, use the password sign-in flow. It returns a user access token (UAT) you pass as the Bearer token.

​
Sign in

curl -X POST https://api-staging.knowledgestack.ai/v1/auth/pw/signin \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'
A successful response returns a UAT: 
{
  "access_token": "eyJ...",
  "token_type": "bearer"
}

​
Use the UAT

Pass it the same way as an API key: 
curl https://api-staging.knowledgestack.ai/v1/users/me \
  -H "Authorization: Bearer eyJ..."

​
Refresh the token

UATs expire. Refresh before making requests if you’re storing tokens across sessions: 
curl -X POST https://api-staging.knowledgestack.ai/v1/auth/uat \
  -H "Authorization: Bearer <current-token>"
The response returns a new access token with a fresh expiry.

​
Sign out

Invalidate the current token: 
curl -X POST https://api-staging.knowledgestack.ai/v1/auth/signout \
  -H "Authorization: Bearer <your-token>"

​
SSO

For tenants configured with a third-party identity provider, use the SSO flow. This is a redirect-based flow — it’s not suitable for direct API access from a server.

​
Initiate SSO

curl -X POST https://api-staging.knowledgestack.ai/v1/auth/sso/initiate \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "tenant_01j...",
    "redirect_uri": "https://your-app.com/auth/callback"
  }'
The response returns a redirect URL: 
{
  "redirect_url": "https://your-idp.com/authorize?..."
}
Redirect your user to that URL. After the user authenticates with the identity provider, they are redirected back to your redirect_uri with a token you can use for subsequent API calls.
SSO requires your tenant to have an identity provider configured. Contact your account administrator to set up SSO for your tenant.

​
Common errors

StatusMeaningFix
401 UnauthorizedToken is missing, malformed, or expiredVerify the Authorization header is formatted as Bearer <token>. Refresh or re-issue the token if expired.
403 ForbiddenToken is valid but lacks permission for the requested resourceCheck the permissions assigned to the user or API key. A user may be authenticated but not authorized to access a specific path.
When debugging auth errors, try calling GET /v1/users/me first. A 200 response confirms your token is valid. A 401 means the token itself is the problem.