v2.4.1

Authentication

Secure your API requests using ConnectHub's authentication system. We support API Keys, OAuth 2.0, and JWT-based authentication for server and client-side applications.

Overview

ConnectHub uses standard HTTP authentication methods. All API requests must be authenticated, and most require proper scopes depending on the endpoint. Choose the authentication method that best fits your application architecture.

💡 Recommendation Use API Keys for server-to-server communication. Use OAuth 2.0 for applications that act on behalf of users. Never expose API keys in client-side code.

API Keys

API keys provide the simplest way to authenticate server-side requests. Generate keys from your ConnectHub Dashboard under Settings → API Access.

cURL

curl https://api.connecthub.com/v2/me \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const response = await fetch('https://api.connecthub.com/v2/me', {
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

Key Type	Access Level	Recommended For
`CH_LIVE_*`	Production	Live applications
`CH_TEST_*`	Sandbox	Development & testing

OAuth 2.0

Use OAuth 2.0 when your application needs to access user data on their behalf. ConnectHub supports the Authorization Code and PKCE flows.

1. Redirect Users to Authorization

URL

https://connecthub.com/oauth/authorize
?client_id=YOUR_CLIENT_ID
&redirect_uri=https://your-app.com/callback
&response_type=code
&scope=read:posts write:messages
&state=random_csrf_token

2. Exchange Code for Token

cURL

curl -X POST https://api.connecthub.com/v2/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE&client_secret=SECRET&redirect_uri=YOUR_REDIRECT_URI"

⚠️ Security Notice Always verify the state parameter returned by ConnectHub matches the one you generated. This prevents CSRF attacks.

JWT Access Tokens

Successful OAuth or API key authentication returns a JWT access token. Include it in the Authorization header for subsequent requests.

JSON Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt_8f7g6h5j4k3l2m1n",
  "scope": "read:posts write:messages"
}

Tokens expire after 1 hour. Use the refresh_token to obtain a new access token without re-authenticating the user.

Error Handling

Authentication failures return standard HTTP error codes. Always handle these gracefully in your application.

Status Code	Error Code	Description
`401`	`invalid_credentials`	Missing or malformed API key/token
`401`	`token_expired`	Access token has expired
`403`	`insufficient_scope`	Token lacks required permissions
`429`	`rate_limited`	Too many authentication attempts

Error Response

{
  "error": {
    "code": "token_expired",
    "message": "The access token has expired. Please refresh or re-authenticate.",
    "status": 401,
    "request_id": "req_8f7g6h5j4k3l2m1n"
  }
}