Partner API

The Partner API enables B2B partners to programmatically provision and manage sota.io users for their customers. Partners authenticate with a dedicated sotap_ API key and can create user accounts, generate API keys, and monitor usage — all through a single API.

Authentication

All partner API requests require the partner API key:

Authorization: Bearer sotap_your_partner_key

Partner keys use the sotap_ prefix (distinct from user sota_ keys). Partner keys are issued during onboarding and shown only once.

Base URL

https://api.sota.io/v1/partner

Provision a User

Creates a new sota.io account for your customer. Returns a one-time API key and password.

POST /v1/partner/users

Request:

{
  "email": "customer@example.com"
}

Response (201 — new user):

{
  "data": {
    "user_id": "uuid",
    "email": "customer@example.com",
    "api_key": "sota_...",
    "password": "auto-generated",
    "created": true
  }
}

Response (200 — existing user, idempotent):

{
  "data": {
    "user_id": "uuid",
    "email": "customer@example.com",
    "created": false
  }
}

Important: The api_key and password are returned only on first creation. Store them securely — they cannot be retrieved again.

Each provisioned user receives:

• Free plan — 5 projects, 256 MB memory, 500 millicores CPU
• API key (sota_ prefix) for programmatic deployments
• Password for logging into the sota.io dashboard

List Your Users

GET /v1/partner/users

Query parameters:

Response:

{
  "data": [
    {
      "id": "uuid",
      "partner_id": "uuid",
      "user_id": "uuid",
      "status": "active",
      "provisioned_at": "2026-02-28T12:00:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "uuid",
    "has_more": false
  }
}

Get User Detail

GET /v1/partner/users/{user_id}

Response:

{
  "data": {
    "user_id": "uuid",
    "email": "customer@example.com",
    "plan": "free",
    "project_count": 2,
    "deployment_count": 5,
    "created_at": "2026-02-28T12:00:00Z"
  }
}

Get User API Keys

Returns key metadata (prefix and status). Full keys are never exposed after creation.

GET /v1/partner/users/{user_id}/api-keys

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "default (partner-provisioned)",
      "key_prefix": "sota_a1b2c3d4",
      "last_used_at": null,
      "created_at": "2026-02-28T12:00:00Z"
    }
  ]
}

Get Aggregate Stats

GET /v1/partner/stats

Response:

{
  "data": {
    "total_users": 15,
    "total_projects": 23,
    "total_deployments": 47,
    "active_users_30d": 8
  }
}

Suspend a User

Temporarily disable a user's access. Suspended users cannot deploy or access the API.

POST /v1/partner/users/{user_id}/suspend

Response:

{
  "data": {
    "status": "suspended"
  }
}

Unsuspend a User

Re-enable a suspended user.

POST /v1/partner/users/{user_id}/unsuspend

Response:

{
  "data": {
    "status": "active"
  }
}

Health Check

Verify your partner authentication is working.

GET /v1/partner/health

Response:

{
  "data": {
    "status": "ok",
    "partner_id": "uuid",
    "partner": "your-partner-name"
  }
}

Integration Flow

1. Your backend calls POST /v1/partner/users with customer email
2. Store the returned api_key and password securely
3. Pass api_key to customer's AI agent or CI/CD pipeline
4. Pass password to customer for dashboard access (optional)
5. Customer deploys via API or CLI using their api_key
6. Monitor usage via GET /v1/partner/stats

Dashboard Access

Partners can manage their users through the admin dashboard:

https://admin.sota.io

The dashboard shows your provisioned users, their projects, and aggregate statistics.

Error Codes

Security

• Partners can only access users they provisioned
• Accessing another partner's users returns 404 (no information leakage)
• API keys are hashed server-side — raw keys are never stored
• All traffic requires HTTPS
• Partner API keys use sotap_ prefix (distinct from user sota_ keys)