API Authentication

Secure authentication is required for all requests to the Cognipeer API. This guide explains how to authenticate your API requests using Personal Access Tokens (PAT).

Personal Access Tokens (Recommended)

Personal Access Tokens (PAT) are the recommended authentication method for API access. They provide secure, long-lived authentication tokens that can be easily managed and revoked.

Creating a Personal Access Token

1. Log in to your Cognipeer workspace
2. Navigate to Settings → Security → Personal Access Tokens
3. Click Create Token
4. Enter a descriptive label (e.g., "Production API", "Development")
5. Copy the generated token immediately - you won't be able to see it again!

The token will look like: pat_kcnlto8e01zg3frarz8l1kvenmhqvtqzjmfnxdvh

Using Personal Access Tokens

All API requests must include your PAT in the Authorization header as a Bearer token:

Authorization: Bearer pat_your-personal-access-token

Example Request

fetch('https://api.cognipeer.com/v1/sdk/peer', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer pat_kcnlto8e01zg3frarz8l1kvenmhqvtqzjmfnxdvh',
    'Content-Type': 'application/json',
    'X-Hook-Id': 'your-channel-hook-id'
  }
})
.then(response => response.json())
.then(data => console.log(data));

With the SDK

When using the official SDK, provide your PAT and hookId during initialization:

import { CognipeerClient } from '@cognipeer/sdk';

const client = new CognipeerClient({
  token: 'pat_kcnlto8e01zg3frarz8l1kvenmhqvtqzjmfnxdvh',
  hookId: 'your-api-channel-hook-id'
});

// Now you can make authenticated requests
const peer = await client.peers.get();
const user = await client.users.get();

API Channels and Hook IDs

In addition to authentication, API requests require a hookId to identify which peer/channel to use:

Creating an API Channel

1. Navigate to your peer's settings
2. Go to the Channels tab
3. Click Add Channel → API Access
4. Name your channel (e.g., "Production API")
5. Copy the generated hookId

Using Hook IDs

Include the hookId in your requests using the X-Hook-Id header or as a request parameter:

// In headers
headers: {
  'Authorization': 'Bearer pat_your-token',
  'X-Hook-Id': 'your-hook-id'
}

// Or in request body
body: JSON.stringify({
  hookId: 'your-hook-id',
  // ... other parameters
})

The SDK handles this automatically when you configure it:

const client = new CognipeerClient({
  token: 'pat_your-token',
  hookId: 'your-hook-id'  // Automatically included in all requests
});

Dual Authentication Support

Most SDK endpoints require only Personal Access Tokens (PAT) for authentication. However, some endpoints support both PAT and API tokens for maximum flexibility:

Endpoints Supporting Both Authentication Methods

The following endpoints work with both PAT tokens and API tokens (hookId-based):

• Contacts API (/sdk/contact)
  • contacts.create() - Create contacts with either token type
  • contacts.get() - Retrieve contacts with either token type
  • contacts.update() - Update contacts with either token type
  • contacts.list() - List contacts with either token type

When to Use Each Method

Use Personal Access Token (PAT) when:

• Building server-side applications
• Need user-specific access control
• Require long-lived authentication
• Working with multiple peers/workspaces

Use API Token (hookId) when:

• Working within a specific API channel context
• Building channel-specific integrations
• Need simpler authentication flow
• Working with single peer/channel

Example: Contacts API with PAT

import { CognipeerClient } from '@cognipeer/sdk';

const client = new CognipeerClient({
  token: 'pat_kcnlto8e01zg3frarz8l1kvenmhqvtqzjmfnxdvh',
  hookId: 'your-hook-id'
});

// Create contact using PAT
const contact = await client.contacts.create({
  email: 'user@example.com',
  name: 'John Doe'
});

Example: Contacts API with API Token

import { CognipeerClient } from '@cognipeer/sdk';

const client = new CognipeerClient({
  token: 'your-api-token',
  hookId: 'your-channel-hook-id'
});

// Create contact using API token - same method, different auth
const contact = await client.contacts.create({
  email: 'user@example.com',
  name: 'John Doe'
});

TIP

The Contacts API automatically detects which authentication method you're using and handles authorization accordingly. You don't need to change your code when switching between authentication methods.

Legacy Token Authentication

Deprecated

Legacy workspace tokens are deprecated. Please migrate to Personal Access Tokens for better security and user-specific access control.

Legacy tokens can still be used but are no longer recommended:

// Old method (deprecated)
const client = new CognipeerClient({
  token: 'workspace-token'
});

Token Security

Treat your Personal Access Tokens like passwords:

Best Practices

• ✅ Use Environment Variables: Store tokens in environment variables, never hardcode
• ✅ Rotate Regularly: Delete and create new tokens periodically
• ✅ Use Descriptive Labels: Name tokens by purpose and environment
• ✅ Revoke Unused Tokens: Delete tokens that are no longer needed
• ✅ Monitor Usage: Check the "Last Used" date in the token list

Security Don'ts

• ❌ Never commit tokens to version control (Git, GitHub, etc.)
• ❌ Never share tokens in publicly accessible areas
• ❌ Never expose tokens in client-side code or browsers
• ❌ Never use production tokens in development/testing

Environment Variables Example

# .env file
COGNIPEER_TOKEN=pat_kcnlto8e01zg3frarz8l1kvenmhqvtqzjmfnxdvh
COGNIPEER_HOOK_ID=bhdwxdpdkndpzolyttqf

// config.js
import { CognipeerClient } from '@cognipeer/sdk';
import dotenv from 'dotenv';

dotenv.config();

export const client = new CognipeerClient({
  token: process.env.COGNIPEER_TOKEN,
  hookId: process.env.COGNIPEER_HOOK_ID
});

Token Management

Viewing Tokens

To view your tokens:

1. Go to Settings → Security → Personal Access Tokens
2. See all your tokens with labels and last used dates
3. Tokens are masked for security (e.g., pat_kcnlto8e...)

Revoking Tokens

To revoke a token:

1. Go to Settings → Security → Personal Access Tokens
2. Click the delete icon next to the token
3. Confirm deletion

WARNING

Revoking a token immediately invalidates it. Any applications using that token will stop working.

Token Expiration

Personal Access Tokens can optionally have expiration dates:

• No Expiration (default): Token remains valid until manually revoked
• Custom Expiration: Set a specific date for automatic expiration

After expiration, the token will no longer authenticate requests.

Troubleshooting

"Authorization Error" or 401 Status

• Verify token starts with pat_ prefix
• Check token hasn't been revoked or expired
• Ensure token is included in the Authorization header
• Verify Bearer prefix is included

"Channel not found" or 404 Status

• Verify hookId is correct
• Check channel hasn't been deleted or disabled
• Ensure hookId is included in headers or body

"Invalid Token" Error

• Token may have been revoked
• Token may have expired
• Token format may be incorrect
• Create a new token if needed

API Reference

For complete API documentation, see:

• Conversation API
• Peer API
• App/Flow API

Support

If you have questions about authentication:

• Check our FAQ
• Contact support at support@cognipeer.com
• Join our Discord community