Authentication API

The Connix Authentication API provides secure access to platform resources using API keys, OAuth2 tokens, and session-based authentication. This reference covers all authentication endpoints and security mechanisms.

Base URL

https://api.connix.io/api/v1
https://console.connix.io/oauth2

Authentication Methods

1. API Key Authentication

API keys provide simple, secure authentication for server-to-server communication.

Header Format:

X-API-Key: cx_1234567890abcdef1234567890abcdef

Key Format:

Prefix: cx_ (Connix API keys)
Length: 32 hexadecimal characters after prefix
Example: cx_1234567890abcdef1234567890abcdef

2. OAuth2 Bearer Token

OAuth2 tokens provide secure authentication for user-facing applications.

Header Format:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

3. Session Authentication

Session-based authentication for web applications using secure cookies.

Cookie:

Cookie: connix_session=s%3A1234567890abcdef.signature

API Key Management

Create API Key

Generate a new API key for programmatic access.

Request:

POST /auth/api-keys

Headers:

Authorization: Bearer your_access_token
Content-Type: application/json

Request Body:

{
  "name": "Production Server Key",
  "description": "API key for production deployment",
  "scopes": ["projects:read", "projects:write", "agents:read", "agents:write"],
  "expires_at": "2025-01-15T00:00:00Z"
}

Example Request:

curl -X POST "https://api.connix.io/api/v1/auth/api-keys" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server Key",
    "description": "API key for production deployment",
    "scopes": ["projects:read", "projects:write", "agents:read", "agents:write"]
  }'

Response:

{
  "id": "key_1234567890abcdef",
  "name": "Production Server Key",
  "description": "API key for production deployment",
  "key": "cx_1234567890abcdef1234567890abcdef",
  "scopes": ["projects:read", "projects:write", "agents:read", "agents:write"],
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2025-01-15T00:00:00Z",
  "last_used": null
}

List API Keys

Retrieve all API keys for the authenticated user.

Request:

GET /auth/api-keys

Parameters:

Parameter	Type	Required	Description
`limit`	integer	No	Number of results (1-100, default: 20)
`offset`	integer	No	Offset for pagination (default: 0)
`active_only`	boolean	No	Show only non-expired keys (default: true)

Example Request:

curl -X GET "https://api.connix.io/api/v1/auth/api-keys?limit=10" \
  -H "Authorization: Bearer your_access_token"

Response:

{
  "api_keys": [
    {
      "id": "key_1234567890abcdef",
      "name": "Production Server Key",
      "description": "API key for production deployment",
      "key_preview": "cx_1234567890abcdef***",
      "scopes": ["projects:read", "projects:write", "agents:read", "agents:write"],
      "created_at": "2024-01-15T10:30:00Z",
      "expires_at": "2025-01-15T00:00:00Z",
      "last_used": "2024-01-15T16:45:00Z"
    },
    {
      "id": "key_9876543210fedcba",
      "name": "Development Key",
      "description": "API key for development environment",
      "key_preview": "cx_9876543210fedcba***",
      "scopes": ["projects:read", "agents:read"],
      "created_at": "2024-01-10T14:20:00Z",
      "expires_at": null,
      "last_used": "2024-01-15T12:30:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "limit": 10,
    "offset": 0,
    "has_more": false
  }
}

Get API Key

Retrieve details of a specific API key.

Request:

GET /auth/api-keys/{key_id}

Example Request:

curl -X GET "https://api.connix.io/api/v1/auth/api-keys/key_1234567890abcdef" \
  -H "Authorization: Bearer your_access_token"

Response:

{
  "id": "key_1234567890abcdef",
  "name": "Production Server Key",
  "description": "API key for production deployment",
  "key_preview": "cx_1234567890abcdef***",
  "scopes": ["projects:read", "projects:write", "agents:read", "agents:write"],
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2025-01-15T00:00:00Z",
  "last_used": "2024-01-15T16:45:00Z",
  "usage_stats": {
    "total_requests": 15847,
    "requests_last_24h": 342,
    "requests_last_7d": 2156,
    "requests_last_30d": 8923
  }
}

Update API Key

Update an API key’s metadata.

Request:

PUT /auth/api-keys/{key_id}

Request Body:

{
  "name": "Updated Production Key",
  "description": "Updated description for production deployment",
  "scopes": ["projects:read", "projects:write", "agents:read"]
}

Example Request:

curl -X PUT "https://api.connix.io/api/v1/auth/api-keys/key_1234567890abcdef" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Production Key",
    "description": "Updated description for production deployment"
  }'

Response:

{
  "id": "key_1234567890abcdef",
  "name": "Updated Production Key",
  "description": "Updated description for production deployment",
  "key_preview": "cx_1234567890abcdef***",
  "scopes": ["projects:read", "projects:write", "agents:read"],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T18:20:00Z",
  "expires_at": "2025-01-15T00:00:00Z",
  "last_used": "2024-01-15T16:45:00Z"
}

Revoke API Key

Permanently revoke an API key.

Request:

DELETE /auth/api-keys/{key_id}

Example Request:

curl -X DELETE "https://api.connix.io/api/v1/auth/api-keys/key_1234567890abcdef" \
  -H "Authorization: Bearer your_access_token"

Response:

{
  "message": "API key revoked successfully",
  "key_id": "key_1234567890abcdef",
  "revoked_at": "2024-01-15T18:30:00Z"
}

OAuth2 Authentication

Authorization Endpoint

Initiate OAuth2 authorization flow.

Request:

GET https://console.connix.io/oauth2/authorize

Parameters:

Parameter	Type	Required	Description
`client_id`	string	Yes	Your application’s client ID
`redirect_uri`	string	Yes	Where to redirect after authorization
`response_type`	string	Yes	Must be `code`
`scope`	string	Yes	Space-separated list of scopes
`state`	string	Yes	Random string for CSRF protection

Available Scopes:

Scope	Description
`read`	Read access to user’s projects and agents
`write`	Full access to create, update, and delete resources
`admin`	Administrative access (organization management)

Example Request:

https://console.connix.io/oauth2/authorize?client_id=your_client_id&redirect_uri=https://yourapp.com/callback&response_type=code&scope=read%20write&state=random_state_string

Token Exchange

Exchange authorization code for access token.

Request:

POST https://console.connix.io/oauth2/token

Headers:

Content-Type: application/x-www-form-urlencoded

Request Body:

grant_type=authorization_code&client_id=your_client_id&client_secret=your_client_secret&code=authorization_code&redirect_uri=https://yourapp.com/callback

Example Request:

curl -X POST "https://console.connix.io/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&client_id=your_client_id&client_secret=your_client_secret&code=auth_code_here&redirect_uri=https://yourapp.com/callback"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "read write"
}

Token Refresh

Refresh an expired access token.

Request:

POST https://console.connix.io/oauth2/token

Request Body:

grant_type=refresh_token&client_id=your_client_id&client_secret=your_client_secret&refresh_token=your_refresh_token

Example Request:

curl -X POST "https://console.connix.io/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&client_id=your_client_id&client_secret=your_client_secret&refresh_token=refresh_token_here"

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "read write"
}

Token Revocation

Revoke an access or refresh token.

Request:

POST https://console.connix.io/oauth2/revoke

Request Body:

token=token_to_revoke&client_id=your_client_id&client_secret=your_client_secret

Example Request:

curl -X POST "https://console.connix.io/oauth2/revoke" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=token_to_revoke&client_id=your_client_id&client_secret=your_client_secret"

Response:

{
  "message": "Token revoked successfully"
}

User Information

Get Current User

Retrieve information about the authenticated user.

Request:

GET /auth/user

Example Request:

curl -X GET "https://api.connix.io/api/v1/auth/user" \
  -H "Authorization: Bearer your_access_token"

Response:

{
  "id": "user_1234567890abcdef",
  "email": "user@example.com",
  "name": "John Doe",
  "avatar_url": "https://gravatar.com/avatar/...",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "email_verified": true,
  "plan": "pro",
  "organizations": [
    {
      "id": "org_1234567890abcdef",
      "name": "Acme Corp",
      "role": "admin",
      "joined_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Update User Profile

Update the authenticated user’s profile information.

Request:

PUT /auth/user

Request Body:

{
  "name": "John Smith",
  "avatar_url": "https://example.com/avatar.jpg"
}

Example Request:

curl -X PUT "https://api.connix.io/api/v1/auth/user" \
  -H "Authorization: Bearer your_access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith"
  }'

Response:

{
  "id": "user_1234567890abcdef",
  "email": "user@example.com",
  "name": "John Smith",
  "avatar_url": "https://example.com/avatar.jpg",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T18:45:00Z",
  "email_verified": true,
  "plan": "pro"
}

Session Management

Get Current Session

Retrieve information about the current session.

Request:

GET /auth/session

Example Request:

curl -X GET "https://api.connix.io/api/v1/auth/session" \
  -H "Authorization: Bearer your_access_token"

Response:

{
  "id": "session_1234567890abcdef",
  "user_id": "user_1234567890abcdef",
  "created_at": "2024-01-15T10:00:00Z",
  "expires_at": "2024-01-16T10:00:00Z",
  "ip_address": "192.168.1.100",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
  "scopes": ["read", "write"]
}

List Active Sessions

Retrieve all active sessions for the authenticated user.

Request:

GET /auth/sessions

Example Request:

curl -X GET "https://api.connix.io/api/v1/auth/sessions" \
  -H "Authorization: Bearer your_access_token"

Response:

{
  "sessions": [
    {
      "id": "session_1234567890abcdef",
      "created_at": "2024-01-15T10:00:00Z",
      "expires_at": "2024-01-16T10:00:00Z",
      "ip_address": "192.168.1.100",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
      "is_current": true,
      "last_activity": "2024-01-15T18:30:00Z"
    },
    {
      "id": "session_9876543210fedcba",
      "created_at": "2024-01-14T15:20:00Z",
      "expires_at": "2024-01-15T15:20:00Z",
      "ip_address": "10.0.0.50",
      "user_agent": "Connix-SDK-Go/1.0.0",
      "is_current": false,
      "last_activity": "2024-01-15T14:00:00Z"
    }
  ]
}

Revoke Session

Revoke a specific session.

Request:

DELETE /auth/sessions/{session_id}

Example Request:

curl -X DELETE "https://api.connix.io/api/v1/auth/sessions/session_9876543210fedcba" \
  -H "Authorization: Bearer your_access_token"

Response:

{
  "message": "Session revoked successfully",
  "session_id": "session_9876543210fedcba"
}

Revoke All Sessions

Revoke all sessions except the current one.

Request:

DELETE /auth/sessions

Example Request:

curl -X DELETE "https://api.connix.io/api/v1/auth/sessions" \
  -H "Authorization: Bearer your_access_token"

Response:

{
  "message": "All sessions revoked successfully",
  "revoked_count": 3
}

Permission Scopes

Available Scopes

Scope	Description	Resources
`projects:read`	Read projects and environments	Projects, Environments
`projects:write`	Create, update, delete projects	Projects, Environments
`agents:read`	Read agents and their data	Agents, Logs, Metrics
`agents:write`	Create, update, delete agents	Agents, Configurations
`organizations:read`	Read organization information	Organizations, Members
`organizations:write`	Manage organization settings	Organizations, Members, Billing
`api_keys:read`	Read API key information	API Keys
`api_keys:write`	Create, update, revoke API keys	API Keys
`admin`	Full administrative access	All Resources

Check Permissions

Verify current token permissions.

Request:

GET /auth/permissions

Example Request:

curl -X GET "https://api.connix.io/api/v1/auth/permissions" \
  -H "Authorization: Bearer your_access_token"

Response:

{
  "scopes": ["projects:read", "projects:write", "agents:read", "agents:write"],
  "permissions": {
    "projects": {
      "read": true,
      "write": true,
      "delete": true
    },
    "agents": {
      "read": true,
      "write": true,
      "delete": true
    },
    "organizations": {
      "read": false,
      "write": false
    },
    "api_keys": {
      "read": false,
      "write": false
    }
  }
}

Rate Limits

Authentication endpoints have specific rate limits:

Endpoint	Limit	Window
`/auth/api-keys` (POST)	10 requests	1 hour
`/auth/api-keys` (GET)	100 requests	1 minute
`/auth/api-keys/:id` (PUT/DELETE)	20 requests	1 minute
`/oauth2/authorize`	20 requests	1 minute
`/oauth2/token`	30 requests	1 minute
`/oauth2/revoke`	30 requests	1 minute
`/auth/user`	100 requests	1 minute
`/auth/sessions`	50 requests	1 minute

Security Best Practices

API Key Security

Never expose API keys in client-side code
Use environment variables to store keys
Rotate keys regularly (every 90 days)
Use minimal required scopes
Monitor key usage for anomalies
Revoke compromised keys immediately

OAuth2 Security

Always validate the state parameter
Use HTTPS for all OAuth flows
Store tokens securely (encrypted)
Implement proper token refresh logic
Use short-lived access tokens
Validate redirect URIs strictly

General Security

Implement proper CSRF protection
Use secure session configuration
Monitor authentication logs
Enable two-factor authentication
Regular security audits

Error Responses

401 Unauthorized

{
  "error": {
    "code": "invalid_token",
    "message": "The access token is invalid or has expired"
  }
}

403 Forbidden

{
  "error": {
    "code": "insufficient_scope",
    "message": "The request requires higher privileges than provided by the access token",
    "required_scopes": ["projects:write"]
  }
}

429 Too Many Requests

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many authentication requests. Try again in 60 seconds.",
    "retry_after": 60
  }
}

Next Steps

API Overview - General API information
Projects API - Manage projects and environments
Agents API - Create and manage AI agents
Error Handling - Complete error reference