Authentication

The Kula API uses Bearer token authentication. Include your token in the Authorization header of every request.

Token Format

Include your API token in the Authorization header:

Authorization: Bearer your_api_token_here

Getting Your Token

1. Log in to your Kula dashboard
2. Go to Settings → API Management
3. Click Create API Key
4. Enter an API key name (e.g., "Careers Page Integration")
5. Choose API type:
   • Job Boards — For career page integrations
   • Application API — For system integrations
6. Click Generate API key
7. Copy and store the token securely

Making Requests

curl -X GET "https://api.kula.ai/v1/job-boards/job-posts" \
  -H "Authorization: Bearer your_api_token_here" \
  -H "Content-Type: application/json"

API Key Types

Type	Access	Use Case
Job Boards	Job board endpoints only	Career page integrations, job listing widgets
Application API	ATS endpoints, narrowed by scopes	System integrations, ATS workflows

Scopes

A token carries a set of scopes that decide which endpoints it can reach. Every endpoint in the Application API reference states the single scope it needs under Required scope — for example, GET /v1/jobs needs jobs:read.

Scopes are named resource:action, and read and write are separate grants. Holding jobs:read does not let a token create or update a job.

Scopes are managed under Settings → API Management. Changing them does not change the token value, so an existing integration keeps working without a redeploy.

Grant only what the integration uses. A token restricted to jobs:read cannot leak candidate data even if it is exposed.

Calling an endpoint without its scope returns 403 ERR_INSUFFICIENT_SCOPE, naming the missing scope:

{
  "error": {
    "code": "ERR_INSUFFICIENT_SCOPE",
    "message": "This API key is missing the required scope: jobs:read"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Add that scope and retry. Tokens issued before scopes were introduced are unrestricted and keep working unchanged until you edit them.

Best Practices

• Store tokens in environment variables
• Use different tokens for each environment
• Rotate tokens periodically
• Never commit tokens to version control
• Never expose Application Api token in client-side code
• Never share tokens between applications

Environment Variables

Store your token securely:

export KULA_API_TOKEN="your_api_token_here"

Then use it in your code:

const token = process.env.KULA_API_TOKEN;

Resetting Your Token

If your token is compromised:

1. Go to Settings → API Management
2. Find the compromised API key and click Revoke
3. Create a new API key following the steps above
4. Update all applications with the new token

Important: Revoking immediately invalidates the old token. Ensure you have the new token ready before updating your applications.

Error Responses

Status	Code	Description
401	ERR_TOKEN_MISSING	No token provided
401	ERR_INVALID_TOKEN	Token is invalid or expired
403	ERR_FEATURE_NOT_ENABLED	API access not enabled
403	ERR_INSUFFICIENT_SCOPE	Token lacks the scope the endpoint requires

Next Steps

• Quickstart — Make your first API call