API Authentication

The Kinbox API uses Bearer token authentication to identify and authorize API requests. This guide explains how to obtain your API token, use it in requests, and follow security best practices.

Overview

Kinbox uses API tokens to authenticate requests. Your API token carries the same permissions as the operator (user) who generated it, so it’s crucial to keep it secure and treat it like a password.

Keep your token secure! Never share your API token publicly, commit it to version control, or expose it in client-side code.

Getting Your API Token

Follow these steps to obtain your API token from the Kinbox platform:

Access your Kinbox account

Navigate to API settings

Go to Settings > Integrations > APIDirect link: https://app.kinbox.com.br/settings/integrations/apps

Generate or copy your token

Click on the API tab
Look for the Token V3 section
If you don’t have a token yet, click Generate Token
Copy your token and store it securely

If you need to regenerate your token (for security reasons), the old token will be immediately revoked.

Using Your API Token

Once you have your token, include it in the Authorization header of all API requests using the Bearer authentication scheme.

Request Format

curl -X GET "https://api-v1.kinbox.com.br/v3/conversations" \
  -H "Authorization: Bearer YOUR_TOKEN_V3_HERE" \
  -H "Content-Type: application/json"

Authentication Header Format

The authorization header must follow this exact format:

Authorization: Bearer <your_token_v3>

Include the word “Bearer” followed by a space
Then add your complete API token
No quotes or additional characters

Token Permissions

Your API token inherits all permissions from the operator account that generated it. This means:

Permission Inheritance: If the operator doesn’t have permission to create contacts, the API token won’t be able to create contacts either.

Common Permission Examples

Action	Required Permission
View conversations	Read conversations
Send messages	Send messages
Create contacts	Create/edit contacts
Manage deals	Access CRM
View reports	View reports
Manage team members	Admin access

For security reasons, it’s recommended to create a dedicated API user account with only the permissions needed for your integration.

Security Best Practices

Follow these security guidelines to protect your API token and account:

1. Use HTTPS Only

Always connect to the Kinbox API using HTTPS. Never send your token over an unencrypted connection.

Good ✓

curl https://api-v1.kinbox.com.br/v3/conversations \
  -H "Authorization: Bearer YOUR_TOKEN"

Bad ✗

curl http://api-v1.kinbox.com.br/v3/conversations \
  -H "Authorization: Bearer YOUR_TOKEN"

2. Store Tokens Securely

Never hardcode tokens in your source code. Use environment variables or secure configuration management:

# .env file (add to .gitignore!)
KINBOX_API_TOKEN=your_token_here

# Access in your application
export KINBOX_API_TOKEN=$(cat .env | grep KINBOX_API_TOKEN | cut -d '=' -f2)

3. Rotate Tokens Regularly

For enhanced security, regenerate your API tokens periodically:

Every 90 days for production environments
Immediately if you suspect a token has been compromised
When team members with token access leave your organization

4. Use Different Tokens for Different Environments

Create separate Kinbox workspaces and tokens for:

Development: For testing and development
Staging: For pre-production testing
Production: For live operations

5. Never Expose Tokens Client-Side

Critical: Never include API tokens in:

Frontend JavaScript code
Mobile app source code
Public repositories
Browser requests visible in Network tab

Instead, proxy API requests through your backend server:

Client → Your Backend → Kinbox API

// Frontend (client.js)
fetch('https://your-backend.com/api/send-message', {
  method: 'POST',
  body: JSON.stringify({ message: 'Hello!' })
});

// Backend (server.js)
app.post('/api/send-message', async (req, res) => {
  // Your backend makes the authenticated request
  const response = await fetch('https://api-v1.kinbox.com.br/v3/messages', {
    headers: {
      'Authorization': `Bearer ${process.env.KINBOX_API_TOKEN}`
    },
    method: 'POST',
    body: JSON.stringify(req.body)
  });
  res.json(await response.json());
});

6. Monitor API Usage

Regularly review your API usage in the Kinbox dashboard:

Go to Settings > Integrations > API
Check the API Logs section
Look for unusual patterns or unauthorized access

7. Implement Rate Limiting

Implement rate limiting in your application to avoid hitting API limits:

Rate Limiting Example

const rateLimit = require('express-rate-limit');

const limiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 60 // 60 requests per minute
});

app.use('/api/', limiter);

Error Handling

Properly handle authentication errors in your application:

Common Authentication Errors

Status Code	Error	Cause	Solution
401	Unauthorized	Missing or invalid token	Check token format and validity
403	Forbidden	Insufficient permissions	Verify operator permissions
429	Too Many Requests	Rate limit exceeded	Implement backoff strategy

Example Error Response

{
  "error": "Unauthorized",
  "message": "Invalid or missing authentication token",
  "statusCode": 401
}

Handling Authentication Errors

try {
  const response = await kinboxAPI.get('/v3/conversations');
  return response.data;
} catch (error) {
  if (error.response?.status === 401) {
    console.error('Authentication failed. Check your API token.');
    // Regenerate token or alert admin
  } else if (error.response?.status === 403) {
    console.error('Permission denied. This token lacks required permissions.');
  }
  throw error;
}

Testing Your Authentication

Verify your authentication is working correctly:

Make a test request

Use this simple request to test your token:

curl -X GET "https://api-v1.kinbox.com.br/v3/conversations" \
  -H "Authorization: Bearer YOUR_TOKEN_V3_HERE"

Check the response

Success (200): Your authentication is working!
Unauthorized (401): Check your token format or regenerate it
Forbidden (403): Your token doesn’t have required permissions

Next Steps

Now that you understand authentication, explore the Kinbox API:

List Contacts

Retrieve and manage contact information

Get Conversations

Access conversation data and history

Manage Campaigns

Create and manage bulk messaging campaigns

Webhooks

Receive real-time notifications for events

Need Help?

If you encounter authentication issues:

Check that your token is correctly copied (no extra spaces)
Verify you’re using HTTPS, not HTTP
Ensure the operator who generated the token has the required permissions
Try regenerating your token
Contact support at [email protected]

Get Started

Core Features

Integrations

Updates

Authentication

API Authentication

Overview

Getting Your API Token

Using Your API Token

Request Format

Authentication Header Format

Token Permissions

Common Permission Examples

Security Best Practices

1. Use HTTPS Only

2. Store Tokens Securely

3. Rotate Tokens Regularly

4. Use Different Tokens for Different Environments

5. Never Expose Tokens Client-Side

6. Monitor API Usage

7. Implement Rate Limiting

Error Handling

Common Authentication Errors

Example Error Response

Handling Authentication Errors

Testing Your Authentication

Next Steps

List Contacts

Get Conversations

Manage Campaigns

Webhooks

Need Help?

Build docs developers (and LLMs) love

Get Started

Core Features

Integrations

Updates

​API Authentication

​Overview

​Getting Your API Token

​Using Your API Token

​Request Format

​Authentication Header Format

​Token Permissions

​Common Permission Examples

​Security Best Practices

​1. Use HTTPS Only

​2. Store Tokens Securely

​3. Rotate Tokens Regularly

​4. Use Different Tokens for Different Environments

​5. Never Expose Tokens Client-Side

​6. Monitor API Usage

​7. Implement Rate Limiting

​Error Handling

​Common Authentication Errors

​Example Error Response

​Handling Authentication Errors

​Testing Your Authentication

​Next Steps

List Contacts

Get Conversations

Manage Campaigns

Webhooks

​Need Help?

Build docs developers (and LLMs) love

API Authentication

Overview

Getting Your API Token

Using Your API Token

Request Format

Authentication Header Format

Token Permissions

Common Permission Examples

Security Best Practices

1. Use HTTPS Only

2. Store Tokens Securely

3. Rotate Tokens Regularly

4. Use Different Tokens for Different Environments

5. Never Expose Tokens Client-Side

6. Monitor API Usage

7. Implement Rate Limiting

Error Handling

Common Authentication Errors

Example Error Response

Handling Authentication Errors

Testing Your Authentication

Next Steps

Need Help?