API Reference

Authentication API

Complete API reference for user authentication, registration, and session management.

Register User

Create a new user account with automatic tenant and welcome credits.

POST /api/v1/auth/register

# Request
curl -X POST https://api.engrami.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "securePassword123",
    "full_name": "John Doe",
    "company": "Acme Inc"
  }'

# Response
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "full_name": "John Doe",
  "tenant_id": "tenant_xyz789",
  "credits": 5000,
  "created_at": "2024-01-15T10:30:00Z"
}

Login

Authenticate a user and receive a JWT access token.

POST /api/v1/auth/login

# Request (form-urlencoded)
curl -X POST https://api.engrami.com/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user@example.com&password=securePassword123"

# Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

Get Current User

Retrieve the authenticated user's profile and tenant information.

GET /api/v1/auth/me

# Request
curl https://api.engrami.com/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Response
{
  "id": "usr_abc123",
  "email": "user@example.com",
  "full_name": "John Doe",
  "is_active": true,
  "tenants": [
    {
      "id": "tenant_xyz789",
      "name": "Acme Inc",
      "role": "owner"
    }
  ]
}

Refresh Token

Get a new access token using a refresh token.

POST /api/v1/auth/refresh

# Request
curl -X POST https://api.engrami.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

# Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}

API Keys

Create API Key

POST /api/v1/auth/api-keys

# Request
curl -X POST https://api.engrami.com/api/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "scopes": ["agents:read", "agents:write", "workflows:execute"],
    "expires_at": "2025-01-01T00:00:00Z"
  }'

# Response
{
  "id": "key_abc123",
  "name": "Production API Key",
  "key": "eng_live_sk_abc123...",  // Only shown once
  "scopes": ["agents:read", "agents:write", "workflows:execute"],
  "created_at": "2024-01-15T10:30:00Z",
  "expires_at": "2025-01-01T00:00:00Z"
}

List API Keys

GET /api/v1/auth/api-keys

# Request
curl https://api.engrami.com/api/v1/auth/api-keys \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Response
{
  "items": [
    {
      "id": "key_abc123",
      "name": "Production API Key",
      "key_prefix": "eng_live_sk_abc...",
      "scopes": ["agents:read", "agents:write"],
      "last_used_at": "2024-01-15T12:00:00Z",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Revoke API Key

DELETE /api/v1/auth/api-keys/{key_id}

# Request
curl -X DELETE https://api.engrami.com/api/v1/auth/api-keys/key_abc123 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# Response
{
  "success": true,
  "message": "API key revoked successfully"
}

Error Responses

# 401 Unauthorized
{
  "error": "unauthorized",
  "message": "Invalid or expired token"
}

# 403 Forbidden
{
  "error": "forbidden",
  "message": "Insufficient permissions for this action"
}

# 422 Validation Error
{
  "error": "validation_error",
  "message": "Invalid request body",
  "details": [
    {"field": "email", "message": "Invalid email format"}
  ]
}

Continue to Agents API