Authentication

Overview

The QODRYX API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard Settings. All API requests must include a valid API key in the header.

Authentication Methods

API Keys

API keys are the primary authentication method for server-to-server communication:

# Include your API key in the Authorization header
curl -X GET "https://api.qodryx.com/v1/projects" \
  -H "Authorization: Bearer qx_live_abc123def456..."

# Or use the X-API-Key header
curl -X GET "https://api.qodryx.com/v1/projects" \
  -H "X-API-Key: qx_live_abc123def456..."

API Key Types

Personal Access Tokens (PAT)

PATs are useful for CLI tools and personal automation scripts:

# Generate a PAT from Dashboard → Settings → API Keys → Create Personal Token

# Use in CLI
qodryx auth login --token qx_pat_abc123...

# Use in API requests
curl -X GET "https://api.qodryx.com/v1/user" \
  -H "Authorization: Bearer qx_pat_abc123..."

OAuth 2.0

For applications that need to act on behalf of users:

# 1. Redirect user to authorization URL
https://auth.qodryx.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  response_type=code&
  scope=read:projects write:workflows&
  state=RANDOM_STATE_STRING

# 2. Exchange authorization code for access token
POST https://auth.qodryx.com/oauth/token
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "code": "AUTHORIZATION_CODE",
  "redirect_uri": "YOUR_REDIRECT_URI",
  "grant_type": "authorization_code"
}

# 3. Response
{
  "access_token": "qx_oauth_abc123...",
  "refresh_token": "qx_refresh_xyz789...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:projects write:workflows"
}

Creating API Keys

Scopes & Permissions

API keys can be restricted to specific scopes:

SDK Authentication

JavaScript/TypeScript

import { Qodryx } from '@qodryx/sdk';

// Initialize with API key
const client = new Qodryx({
  apiKey: process.env.QODRYX_API_KEY,
});

// Make authenticated requests
const projects = await client.projects.list();

Python

from qodryx import Qodryx

# Initialize with API key
client = Qodryx(api_key=os.environ['QODRYX_API_KEY'])

# Make authenticated requests
projects = client.projects.list()

CLI

# Authenticate CLI
qodryx auth login

# Or use environment variable
export QODRYX_API_KEY=qx_live_abc123...
qodryx projects list

Token Refresh

OAuth access tokens expire after 1 hour. Use the refresh token to get a new access token:

POST https://auth.qodryx.com/oauth/token
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "refresh_token": "qx_refresh_xyz789...",
  "grant_type": "refresh_token"
}

Error Responses

Authentication errors return appropriate HTTP status codes:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key provided",
    "details": "The API key 'qx_live_...' does not exist or has been revoked"
  }
}

Security Best Practices

Next Steps