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": "[email protected]",
  "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": "[email protected]",
  "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

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

OAuth2 Security

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

General Security

1. Implement proper CSRF protection
2. Use secure session configuration
3. Monitor authentication logs
4. Enable two-factor authentication
5. 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