management-api

Management API

The Management API is intended for back-office systems and administrative integrations. It enables you to configure, launch, and operate your commercial logic on Basta.

Common Responsibilities

• Creating and updating auctions
• Managing inventory and item metadata
• Defining pricing, bidding rules, and time-based conditions
• Issuing bidder tokens for secure user access to the Client API

Authentication

All requests to the Management API must be authenticated with headers. See 🔓 Getting Started for details on obtaining your API credentials.

Required Headers

{
  "x-account-id": "YOUR_ACCOUNT_ID",
  "x-api-key": "YOUR_API_KEY"
}

Endpoints

🔗 GraphQL Explorer: management-api.basta.app/graphql

Explore available GraphQL endpoints in the interactive playground.

Example: Creating an Auction

mutation CreateSale {
  createSale(input: {
    title: "Summer Auction 2024"
    description: "Fine art and collectibles"
    startDate: "2024-07-01T10:00:00Z"
    endDate: "2024-07-15T20:00:00Z"
  }) {
    id
    title
    status
  }
}

Example: Issuing a Bidder Token

mutation CreateBidderToken {
  createBidderToken(input: {
    userId: "user-123"
    ttl: 3600
  }) {
    token
    expiresAt
  }
}

This token can then be used by your users to authenticate with the Client API.

Code Examples

Node.js/TypeScript

import fetch from 'node-fetch';

const MANAGEMENT_API_URL = 'https://management-api.basta.app/graphql';

async function createSale() {
  const response = await fetch(MANAGEMENT_API_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-account-id': process.env.BASTA_ACCOUNT_ID,
      'x-api-key': process.env.BASTA_API_KEY
    },
    body: JSON.stringify({
      query: `
        mutation CreateSale($input: CreateSaleInput!) {
          createSale(input: $input) {
            id
            title
            status
          }
        }
      `,
      variables: {
        input: {
          title: 'Summer Auction 2024',
          description: 'Fine art and collectibles',
          startDate: '2024-07-01T10:00:00Z',
          endDate: '2024-07-15T20:00:00Z'
        }
      }
    })
  });

  const result = await response.json();
  return result.data.createSale;
}

Ruby

require 'net/http'
require 'json'

class BastaManagementAPI
  API_URL = 'https://management-api.basta.app/graphql'

  def initialize(account_id, api_key)
    @account_id = account_id
    @api_key = api_key
  end

  def create_sale(title:, description:, start_date:, end_date:)
    query = <<~GRAPHQL
      mutation CreateSale($input: CreateSaleInput!) {
        createSale(input: $input) {
          id
          title
          status
        }
      }
    GRAPHQL

    variables = {
      input: {
        title: title,
        description: description,
        startDate: start_date,
        endDate: end_date
      }
    }

    execute_query(query, variables)
  end

  private

  def execute_query(query, variables = {})
    uri = URI(API_URL)
    request = Net::HTTP::Post.new(uri)
    request['Content-Type'] = 'application/json'
    request['x-account-id'] = @account_id
    request['x-api-key'] = @api_key
    request.body = JSON.generate({
      query: query,
      variables: variables
    })

    response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
      http.request(request)
    end

    JSON.parse(response.body)
  end
end

# Usage
api = BastaManagementAPI.new(
  ENV['BASTA_ACCOUNT_ID'],
  ENV['BASTA_API_KEY']
)

result = api.create_sale(
  title: 'Summer Auction 2024',
  description: 'Fine art and collectibles',
  start_date: '2024-07-01T10:00:00Z',
  end_date: '2024-07-15T20:00:00Z'
)

Best Practices

1. Secure Your Credentials: Never expose your API key in client-side code
2. Use Environment Variables: Store credentials in environment variables
3. Error Handling: Always handle GraphQL errors appropriately
4. Rate Limiting: Respect rate limits to ensure smooth operations
5. Idempotency: Use idempotency keys for critical mutations

Related Documentation

• API Overview
• Client API
• Getting Started
• Webhooks

Support

For questions about the Management API:

• Email: hi@basta.app
• Documentation: docs.basta.ai