API Overview

Programmatic access to all Automatum platform features through a secure RESTful API with OAuth 2.0 authentication.

Introduction

The Automatum API allows you to integrate marketplace operations into your existing workflows, automate repetitive tasks, and build custom solutions. Whether you're syncing customer data to your CRM, automating metering submissions, or building a custom dashboard, our API provides comprehensive access to all platform features.

Base URL

https://api.automatum.io/api/v1

Quick Start

Get started with the Automatum API in 3 steps:

1. Create OAuth Application

Navigate to Settings > Integrations > API Access in your Automatum dashboard and create a new OAuth application:

json

{
  "name": "My Integration",
  "description": "Production integration for CRM sync",
  "scopes": ["read:customers", "read:entitlements", "write:metering"]
}

You'll receive a client_id and client_secret.

2. Get Access Token

Exchange your credentials for an access token:

bash

curl -X POST https://api.automatum.io/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

json

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read:customers read:entitlements write:metering"
}

3. Make API Requests

Use the access token to make authenticated requests:

bash

curl -X GET https://api.automatum.io/api/v1/customers \
  -H "Authorization: Bearer eyJhbGc..."

Need More Details?

See the complete Authentication Guide for OAuth 2.0 setup, token management, and security best practices.

Authentication

The Automatum API uses OAuth 2.0 Client Credentials flow for secure, server-to-server authentication.

Why OAuth 2.0?

Secure: Industry-standard authentication
Scoped Access: Fine-grained permissions control
Revocable: Tokens can be invalidated immediately
Auditable: Track all API access by application

OAuth Scopes

Control what your application can access:

Scope	Description
`read:customers`	View customer information
`write:customers`	Create and update customers
`read:entitlements`	View entitlements
`read:analytics`	Access analytics data
`write:metering`	Submit metering data
`read:private-offers`	View private offers
`write:private-offers`	Create and update private offers

Security Best Practices

Keep Credentials Secure

Never commit client_secret to version control
Store credentials in environment variables or secrets manager
Rotate credentials regularly (recommended: every 30-90 days)
Use minimum required scopes for each application
Monitor API usage for anomalies

Request Format

Headers

Required headers:

http

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Optional headers:

http

X-Idempotency-Key: unique-request-id
X-Request-ID: custom-tracking-id

Request Body

Send data as JSON:

json

{
  "vendor": "aws",
  "customerId": "cust_123",
  "listingId": "listing_456"
}

Response Format

Success Response

json

{
  "code": 200,
  "data": {
    "id": "obj_123",
    "status": "active",
    "createdAt": "2026-01-16T10:00:00Z"
  }
}

Error Response

json

{
  "code": 400,
  "message": "Invalid request parameters",
  "errors": [
    {
      "field": "customerId",
      "message": "Customer ID is required"
    }
  ]
}

Status Codes

Code	Meaning	Description
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Rate Limits

Standard Limits

1000 requests per hour per API key
50 requests per minute burst limit

Headers

Check your rate limit status:

http

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1642334400

Exceeding Limits

When rate limited:

json

{
  "code": 429,
  "message": "Rate limit exceeded",
  "retryAfter": 60
}

Wait for the retryAfter seconds before retrying.

Pagination

List endpoints support pagination:

bash

GET /api/listing?page=2&limit=50

Parameters

page: Page number (default: 1)
limit: Items per page (default: 20, max: 100)

Response

json

{
  "code": 200,
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 247,
    "pages": 5
  }
}

Filtering

Filter results using query parameters:

bash

GET /api/private-offer?status=active&vendor=aws

Common Filters

status: Filter by status
vendor: Filter by marketplace (aws, azure)
listing: Filter by listing ID
customer: Filter by customer ID
createdAt: Filter by creation date

Date Filtering

bash

# Greater than
?createdAt[gt]=2026-01-01

# Less than
?createdAt[lt]=2026-12-31

# Range
?createdAt[gte]=2026-01-01&createdAt[lte]=2026-12-31

Sorting

Sort results:

bash

GET /api/customer?sort=-createdAt,name

Prefix with - for descending order
Multiple fields separated by commas

Idempotency

Prevent duplicate operations using idempotency keys:

bash

curl -X POST https://api.automatum.io/v1/private-offer \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{"vendor": "aws", ...}'

TIP

Use UUIDs or unique transaction IDs as idempotency keys

Webhooks

Receive real-time notifications for events:

Supported Events

privateOffer.created
privateOffer.accepted
contract.expiring
metering.confirmed
metering.failed
customer.created
entitlement.updated

Webhook Payload

json

{
  "event": "privateOffer.accepted",
  "timestamp": "2026-01-16T10:00:00Z",
  "data": {
    "id": "offer_123",
    "customerId": "cust_456",
    "status": "accepted"
  }
}

Signature Verification

Verify webhook authenticity:

typescript

import crypto from 'crypto';

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return digest === signature;
}

SDKs and Libraries

Official SDKs

Node.js:

bash

npm install @automatum/sdk

typescript

import Automatum from '@automatum/sdk';

const automatum = new Automatum({
  apiKey: process.env.AUTOMATUM_API_KEY
});

const offers = await automatum.privateOffers.list();

Python:

bash

pip install automatum-sdk

python

from automatum import Automatum

automatum = Automatum(api_key=os.environ['AUTOMATUM_API_KEY'])
offers = automatum.private_offers.list()

Coming Soon:

Go
Java
Ruby
PHP

API Resources

Core Resources

All API endpoints are documented in the API Reference:

Private Offers - Manage custom deals
Listings - Product management
Customers - Customer data
Metering Events - Usage reporting
Entitlements - Access rights

Examples

Create a Private Offer

typescript

const offer = await fetch('https://api.automatum.io/v1/private-offer', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    vendor: 'aws',
    listingId: 'listing_123',
    customerId: 'cust_456',
    pricing: {
      discountPercentage: 20,
      duration: 12
    }
  })
});

Report Usage

typescript

const metering = await fetch('https://api.automatum.io/v1/metering-event', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_abc123...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    vendor: 'aws',
    customerId: 'cust_123',
    listingId: 'listing_456',
    dimension: 'api_calls',
    quantity: 1000,
    timestamp: new Date().toISOString()
  })
});

Get Customer List

typescript

const customers = await fetch(
  'https://api.automatum.io/v1/customer?status=active',
  {
    headers: {
      'Authorization': 'Bearer sk_live_abc123...'
    }
  }
);

Testing

Sandbox Environment

Test API calls without affecting production:

https://sandbox-api.automatum.io/v1

Test Credentials

Use test API keys (prefix: sk_test_) for development.

Best Practices

Use HTTPS: Always use secure connections
Handle Errors: Implement proper error handling
Retry Logic: Use exponential backoff for retries
Cache Responses: Cache when appropriate
Monitor Usage: Track API usage and errors
Keep Keys Secure: Never expose API keys

Error Handling

typescript

try {
  const response = await automatumAPI.createOffer(data);
} catch (error) {
  if (error.code === 400) {
    // Handle validation errors
    console.error('Validation failed:', error.errors);
  } else if (error.code === 429) {
    // Handle rate limiting
    await sleep(error.retryAfter * 1000);
    // Retry request
  } else {
    // Handle other errors
    console.error('API error:', error.message);
  }
}

API Overview ​

Introduction ​

Base URL ​

Quick Start ​

1. Create OAuth Application ​

2. Get Access Token ​

3. Make API Requests ​

Authentication ​

Why OAuth 2.0? ​

OAuth Scopes ​

Security Best Practices ​

Request Format ​

Headers ​

Request Body ​

Response Format ​

Success Response ​

Error Response ​

Status Codes ​

Rate Limits ​

Standard Limits ​

Headers ​

Exceeding Limits ​

Pagination ​

Parameters ​

Response ​

Filtering ​

Common Filters ​

Date Filtering ​

Sorting ​

Idempotency ​

Webhooks ​

Supported Events ​

Webhook Payload ​

Signature Verification ​

SDKs and Libraries ​

Official SDKs ​

API Resources ​

Core Resources ​

Examples ​

Create a Private Offer ​

Report Usage ​

Get Customer List ​

Testing ​

Sandbox Environment ​

Test Credentials ​

Best Practices ​

Error Handling ​

Support ​

Documentation ​

Help ​

Next Steps ​

API Overview

Introduction

Base URL

Quick Start

1. Create OAuth Application

2. Get Access Token

3. Make API Requests

Authentication

Why OAuth 2.0?

OAuth Scopes

Security Best Practices

Request Format

Headers

Request Body

Response Format

Success Response

Error Response

Status Codes

Rate Limits

Standard Limits

Headers

Exceeding Limits

Pagination

Parameters

Response

Filtering

Common Filters

Date Filtering

Sorting

Idempotency

Webhooks

Supported Events

Webhook Payload

Signature Verification

SDKs and Libraries

Official SDKs

API Resources

Core Resources

Examples

Create a Private Offer

Report Usage

Get Customer List

Testing

Sandbox Environment

Test Credentials

Best Practices

Error Handling

Support

Documentation

Help

Next Steps