API Overview

Complete reference for Authonomy's REST API

API Reference

Authonomy provides a comprehensive REST API for all platform functionality. This reference covers authentication, user management, policy enforcement, and analytics.

Base URLs

Authonomy APIs are available in multiple environments:

Sandbox: https://api-sandbox.authonomy.io/v1
Production: https://api.authonomy.io/v1

Authentication

All API requests require authentication using an API key:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.authonomy.io/v1/customers

Getting API Keys

Log into your Authonomy Dashboard
Navigate to Settings → API Keys
Click Generate New Key
Choose appropriate permissions for your use case

API Key Permissions

API keys can be scoped to specific operations:

Read-only: View configurations and data
Configuration: Manage customer and policy settings
Authentication: Handle user authentication flows
Full Access: All operations (use carefully)

Core API Categories

Authentication API

Handle user authentication flows and session management.

Key Endpoints

POST /auth/authorize - Initiate authentication
POST /auth/token - Exchange code for tokens
POST /auth/refresh - Refresh access tokens
DELETE /auth/logout - End user sessions

Example: Start Authentication Flow

curl -X POST https://api.authonomy.io/v1/auth/authorize \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "acme-corp",
    "return_url": "https://yourapp.com/callback",
    "scopes": ["profile", "email", "groups"]
  }'

Response:

{
  "authorization_url": "https://auth.authonomy.io/authorize?code=abc123...",
  "state": "eyJhbGciOiJIUzI1NiJ9...",
  "expires_in": 600
}

Customer Management API

Manage customer configurations, IDP settings, and policies.

Key Endpoints

GET /customers - List customers
POST /customers - Create customer
PUT /customers/{id} - Update customer
POST /customers/{id}/idp - Configure IDP

Example: Configure Customer IDP

curl -X POST https://api.authonomy.io/v1/customers/acme-corp/idp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "okta",
    "domain": "acme-corp.okta.com",
    "client_id": "customer_provided_client_id",
    "client_secret": "customer_provided_secret",
    "scopes": ["openid", "profile", "email", "groups"]
  }'

Policy Management API

Create and manage access control policies.

Key Endpoints

GET /policies - List policies
POST /policies - Create policy
PUT /policies/{id} - Update policy
POST /customers/{id}/policies - Assign policies

Example: Create MFA Policy

curl -X POST https://api.authonomy.io/v1/policies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "require-mfa",
    "description": "Require multi-factor authentication",
    "type": "authentication",
    "conditions": {
      "mfa_required": true,
      "max_session_duration": 28800
    }
  }'

Analytics API

Access identity analytics, audit logs, and reporting data.

Key Endpoints

GET /analytics/dashboard - Dashboard metrics
GET /analytics/events - Event history
GET /analytics/users - User analytics
GET /audit/logs - Audit trail

Example: Get Authentication Events

curl "https://api.authonomy.io/v1/analytics/events?type=authentication&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Request Format

Headers

All requests must include:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Request Body

Use JSON for all request bodies:

{
  "customer_id": "acme-corp",
  "parameter": "value",
  "nested_object": {
    "key": "value"
  }
}

Response Format

Success Responses

Successful responses return JSON with relevant data:

{
  "success": true,
  "data": {
    "id": "customer-123",
    "name": "Acme Corp"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Error Responses

Errors include descriptive messages and error codes:

{
  "success": false,
  "error": {
    "code": "INVALID_CUSTOMER",
    "message": "Customer 'invalid-id' not found",
    "details": {
      "customer_id": "invalid-id"
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z",
    "request_id": "req_abc123"
  }
}

HTTP Status Codes

Authonomy uses standard HTTP status codes:

200 - Success
201 - Created successfully
400 - Bad request (invalid parameters)
401 - Unauthorized (invalid API key)
403 - Forbidden (insufficient permissions)
404 - Not found
422 - Validation error
429 - Rate limit exceeded
500 - Internal server error

Rate Limits

API requests are rate limited to ensure platform stability:

Authentication API: 1000 requests/minute
Management API: 500 requests/minute
Analytics API: 100 requests/minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642241400

Pagination

List endpoints support pagination:

curl "https://api.authonomy.io/v1/customers?page=2&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response includes pagination metadata:

{
  "success": true,
  "data": [...],
  "pagination": {
    "current_page": 2,
    "total_pages": 5,
    "total_items": 247,
    "page_size": 50
  }
}

Filtering & Sorting

Many endpoints support filtering and sorting:

# Filter customers by status
curl "https://api.authonomy.io/v1/customers?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Sort by creation date
curl "https://api.authonomy.io/v1/customers?sort=created_at&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Webhooks

Receive real-time events via webhooks:

Configure Webhook Endpoint

curl -X POST https://api.authonomy.io/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhook",
    "events": ["user.authenticated", "policy.violated"],
    "secret": "your-webhook-secret"
  }'

Webhook Payload

{
  "id": "evt_123",
  "type": "user.authenticated",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "user": {
      "id": "user_456",
      "email": "john@acme-corp.com",
      "customer_id": "acme-corp"
    },
    "session": {
      "id": "sess_789",
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0..."
    }
  }
}

SDK Libraries

Official SDKs available for popular languages:

Node.js

npm install @authonomy/sdk

import { AuthonomyClient } from '@authonomy/sdk';

const authonomy = new AuthonomyClient({
  apiKey: 'YOUR_API_KEY',
  environment: 'production'
});

Python

pip install authonomy

from authonomy import AuthonomyClient

authonomy = AuthonomyClient(
    api_key='YOUR_API_KEY',
    environment='production'
)

Testing

Use the sandbox environment for development and testing:

const authonomy = new AuthonomyClient({
  apiKey: 'sandbox_key_123',
  environment: 'sandbox'
});

Sandbox features:

No real IDP connections required
Mock user data for testing
Full API functionality
Separate from production data

Next Steps

Explore specific API categories:

Authentication API - Complete auth flow reference
Customer Management - Customer configuration APIs
Policy Management - Access control APIs
Analytics API - Reporting and insights

Need help? Contact support or check our troubleshooting guide.