Authentication

CohesionXL uses OAuth 2.0 for API authentication. All API requests must include a valid access token in the Authorization header.

Getting Started

1. Create an API Client

Navigate to Settings → API Clients in CohesionXL and create a new client. You'll receive a client_id and client_secret.

2. Obtain an Access Token

Exchange your credentials for an access token:

curl -X POST https://api.cohesionxl.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your_client_id",
    "client_secret": "your_client_secret"
  }'

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

3. Use the Token

Include the token in all API requests:

curl https://api.cohesionxl.com/v1/initiatives \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

Token Format

Access tokens are RS256-signed JWTs issued by Auth0. Each token includes:

| Claim | Description | |-------|-------------| | sub | User or client identifier | | org_id | Organization ID | | permissions | Array of granted permissions | | exp | Token expiration timestamp |

API Keys

For server-to-server integrations, you can also use API keys:

curl https://api.cohesionxl.com/v1/initiatives \
  -H "X-API-Key: cxl_live_abc123..."

API keys are scoped to a single organization and inherit the permissions of the user who created them.

Rate Limits

| Plan | Requests / minute | |------|-------------------| | Core Planning | 60 | | Portfolio + Intelligence | 300 | | Operating System | 1,000 |

Rate limit headers are included in every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1700000000

Error Responses

Authentication errors return a 401 Unauthorized response:

{
  "error": "unauthorized",
  "message": "Invalid or expired access token"
}