Authentication

CODITECT supports multiple authentication methods depending on your use case.

Authentication Methods

Method	Use Case
OAuth2	Web applications, user login
API Tokens	Server-to-server, CLI, CI/CD
Session Tokens	Browser sessions (automatic)

OAuth2 Authentication

For applications that need to act on behalf of users.

Authorization Code Flow

Step 1: Redirect to Authorization

GET https://auth.coditect.ai/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=read:projects write:projects
  &state=random_state_string

Step 2: Exchange Code for Tokens

POST https://auth.coditect.ai/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://yourapp.com/callback

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:projects write:projects"
}

Available Scopes

Scope	Description
read:profile	Read user profile
write:profile	Update user profile
read:projects	Read project data
write:projects	Create/modify projects
read:org	Read organization data
admin:org	Full organization management
read:licenses	Read license information
manage:licenses	Acquire/release licenses

API Tokens

For server-to-server communication and automation.

Generate Token

1. Navigate to Settings → API Keys
2. Click Generate New Token
3. Select scopes and set expiration
4. Copy the token (shown only once)

Using API Tokens

Include the token in the Authorization header:

curl -H "Authorization: Bearer cdt_live_abc123..." \
  https://api.coditect.ai/v1/projects

Token Types

Prefix	Type	Environment
cdt_live_	Production	Live data
cdt_test_	Sandbox	Test data

Token Best Practices

Security

• Rotate tokens regularly (every 90 days recommended)
• Use minimal scopes needed for your integration
• Store securely - never commit tokens to code
• Monitor usage in the dashboard

Session Tokens

Automatic for browser-based sessions.

Login

POST /v1/auth/login

curl -X POST https://api.coditect.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response:

{
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "name": "John Doe"
    },
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
    "expires_at": "2026-01-09T11:30:00Z"
  }
}

Register

POST /v1/auth/register

curl -X POST https://api.coditect.ai/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "secure-password-123",
    "name": "John Doe"
  }'

Refresh Token

POST /v1/auth/refresh

curl -X POST https://api.coditect.ai/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
  }'

Logout

POST /v1/auth/logout

curl -X POST https://api.coditect.ai/v1/auth/logout \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Get Current User

GET /v1/auth/me

curl https://api.coditect.ai/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "name": "John Doe",
    "avatar_url": "https://avatars.coditect.ai/usr_abc123",
    "created_at": "2026-01-01T00:00:00Z",
    "organization": {
      "id": "org_xyz789",
      "name": "Acme Engineering",
      "role": "admin"
    }
  }
}

Two-Factor Authentication

If 2FA is enabled, login requires an additional step:

Step 1: Initial Login

curl -X POST https://api.coditect.ai/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "your-password"
  }'

Response (2FA required):

{
  "data": {
    "requires_2fa": true,
    "challenge_token": "ch_abc123...",
    "method": "totp"
  }
}

Step 2: Submit 2FA Code

curl -X POST https://api.coditect.ai/v1/auth/2fa/verify \
  -H "Content-Type: application/json" \
  -d '{
    "challenge_token": "ch_abc123...",
    "code": "123456"
  }'

Error Responses

Invalid Credentials

{
  "error": {
    "code": "invalid_credentials",
    "message": "The email or password is incorrect"
  }
}

Token Expired

{
  "error": {
    "code": "token_expired",
    "message": "The access token has expired. Please refresh."
  }
}

Insufficient Scope

{
  "error": {
    "code": "insufficient_scope",
    "message": "This action requires the 'write:projects' scope"
  }
}

SDK Examples

Python

from coditect import Client

# With API token
client = Client(api_key="cdt_live_abc123...")

# With OAuth2
client = Client(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)
access_token = client.oauth.get_token(code="AUTHORIZATION_CODE")

JavaScript

import { CoditectClient } from '@coditect/sdk';

// With API token
const client = new CoditectClient({
  apiKey: 'cdt_live_abc123...'
});

// Get current user
const user = await client.auth.me();