Authentication Overview

ChordianAI API uses AWS Cognito User Pools with JWT (JSON Web Tokens) for secure authentication and authorization.

Authentication Flow

Token Types

ChordianAI uses three types of tokens:

1. ID Token (from Cognito)

Property	Value
Issuer	AWS Cognito User Pool
Verification	JWKS (JSON Web Key Set)
Purpose	Initial authentication
Lifespan	Short-lived (typically 1 hour)

2. Session JWT (Server-side)

Property	Value
Algorithm	HS256
Expiration	15 days
Storage	Client-side (localStorage or sessionStorage)
Library	`jose`
Purpose	API authentication

3. Refresh Token

Property	Value
Cookie Type	`httpOnly`
Expiration	30 days
Purpose	Renew session JWT without re-login
Security	Protected from XSS attacks

Quick Start

import requests
 
# 1. Login
response = requests.post(
    "https://chordian-core.chordian.ai/api/auth/login",
    json={
        "username": "your-email@example.com",
        "password": "your-password"
    }
)
 
data = response.json()
session_token = data["token"]
 
# 2. Use token in API calls
headers = {
    "Authorization": f"Bearer {session_token}",
    "Content-Type": "application/json"
}
 
workflow_response = requests.post(
    "https://chordian-core.chordian.ai/api/workflow/start",
    headers=headers,
    json={
        "prompt": "Find SaaS companies",
        "serviceId": "your-service-id"
    }
)

// 1. Login
const loginResponse = await fetch(
  'https://chordian-core.chordian.ai/api/auth/login',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      username: 'your-email@example.com',
      password: 'your-password'
    }),
    credentials: 'include' // Important for cookies
  }
);
 
const { token } = await loginResponse.json();
 
// 2. Use token in API calls
const workflowResponse = await fetch(
  'https://chordian-core.chordian.ai/api/workflow/start',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      prompt: 'Find SaaS companies',
      serviceId: 'your-service-id'
    })
  }
);

import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
 
// 1. Login
CloseableHttpClient client = HttpClients.createDefault();
HttpPost loginRequest = new HttpPost(
    "https://chordian-core.chordian.ai/api/auth/login"
);
 
String loginJson = "{\"username\":\"your-email@example.com\"," +
                  "\"password\":\"your-password\"}";
loginRequest.setEntity(new StringEntity(loginJson));
loginRequest.setHeader("Content-Type", "application/json");
 
var loginResponse = client.execute(loginRequest);
String loginBody = EntityUtils.toString(loginResponse.getEntity());
JsonObject loginData = JsonParser.parseString(loginBody).getAsJsonObject();
String token = loginData.get("token").getAsString();
 
// 2. Use token in API calls
HttpPost workflowRequest = new HttpPost(
    "https://chordian-core.chordian.ai/api/workflow/start"
);
workflowRequest.setHeader("Authorization", "Bearer " + token);
workflowRequest.setHeader("Content-Type", "application/json");
 
String workflowJson = "{\"prompt\":\"Find SaaS companies\"," +
                     "\"serviceId\":\"your-service-id\"}";
workflowRequest.setEntity(new StringEntity(workflowJson));
 
var workflowResponse = client.execute(workflowRequest);

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json.Linq;
 
// 1. Login
using var client = new HttpClient();
var handler = new HttpClientHandler
{
    UseCookies = true // Important for refresh tokens
};
 
var loginPayload = new
{
    username = "your-email@example.com",
    password = "your-password"
};
 
var loginContent = new StringContent(
    JsonConvert.SerializeObject(loginPayload),
    Encoding.UTF8,
    "application/json"
);
 
var loginResponse = await client.PostAsync(
    "https://chordian-core.chordian.ai/api/auth/login",
    loginContent
);
 
var loginResult = await loginResponse.Content.ReadAsStringAsync();
var loginJson = JObject.Parse(loginResult);
var token = loginJson["token"].ToString();
 
// 2. Use token in API calls
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}");
 
var workflowPayload = new
{
    prompt = "Find SaaS companies",
    serviceId = "your-service-id"
};
 
var workflowContent = new StringContent(
    JsonConvert.SerializeObject(workflowPayload),
    Encoding.UTF8,
    "application/json"
);
 
var workflowResponse = await client.PostAsync(
    "https://chordian-core.chordian.ai/api/workflow/start",
    workflowContent
);

Security Best Practices

⚠️ Warning: Never expose your credentials or tokens in client-side code, version control, or logs.

1. Token Storage

Method	Security Level	Recommended For
`httpOnly` cookie (refresh token)	✅ High	Production
Server-side session	✅ High	Production
`localStorage`	⚠️ Medium	Development only
`sessionStorage`	⚠️ Medium	Development only
JavaScript variables	❌ Low	Never

2. Always Use HTTPS

All API calls must use HTTPS to prevent token interception.

3. Token Expiration

Session JWT: 15 days
Refresh Token: 30 days
Implement automatic token refresh before expiration

4. Logout

Always clear tokens and cookies on logout:

// Logout example
await fetch('https://chordian-core.chordian.ai/api/auth/logout', {
  method: 'POST',
  credentials: 'include'
});
 
// Clear client-side storage
localStorage.removeItem('token');