Getting Started

This guide walks you through authenticating with the ZopNight API and making your first request.

Prerequisites

• A ZopNight account with at least one organization
• At least one connected cloud account (AWS, GCP, or Azure)
• An API client or curl for making HTTP requests

Base URL

All API requests are made to the gateway endpoint:

https://api.zop.dev

Authentication

First, obtain an access token by logging in. ZopNight supports email/password, Google, GitHub, and SAML authentication.

Step 1: Login

curl -X POST https://api.zop.dev/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@company.com",
    "password": "your-password",
    "provider": "email"
  }'

{
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiIs...",
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
  }
}

Step 2: Select an Organization

The login response does not include your organizations. List them, then refresh the token with the organization you want to work in. The new access token is scoped to that organization.

curl https://api.zop.dev/organisations \
  -H "Authorization: Bearer <access_token>"

curl -X POST https://api.zop.dev/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
    "claims": { "tenant-id": "3f6c2a9e-8b1d-4c7e-9f2a-1d5e6b7c8a90" }
  }'

Organization IDs are UUIDs.

Step 3: Use the Token

Include the access token in all subsequent requests via the Authorization header:

curl https://api.zop.dev/resources \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

See the full Authentication guide for token refresh, SSO, and more.

Response Format

All API responses are wrapped in a standard envelope:

{
  "data": {
    "id": "7c1e4b2a-5d3f-4a6b-9c8d-2e1f0a3b4c5d",
    "name": "Business Hours"
  }
}

Errors come in more than one shape. Errors from the platform services carry an object; errors raised by the gateway itself (for example 401 or 429) carry a string. Branch on the type of error rather than assuming one shape. See Error Handling.

{
  "error": { "message": "schedule not found" }
}

{
  "error": "rate limit exceeded"
}

Pagination

Most list endpoints page with page and limit. GET /resources, for example, accepts:

Parameter names are not uniform across the API: a few endpoints use size instead of limit, and some do not support sorting. Unknown parameters are ignored rather than rejected, so check each endpoint’s page for the names it accepts.

curl "https://api.zop.dev/resources?page=2&limit=50&sort_by=name&sort_order=asc" \
  -H "Authorization: Bearer <token>"

Your First API Call

Let’s list your discovered cloud resources:

curl https://api.zop.dev/resources \
  -H "Authorization: Bearer <token>"

{
  "data": {
    "items": [
      {
        "id": "0b7d5c3e-2f1a-4e9b-8c6d-5a4b3c2d1e0f",
        "name": "web-server-prod",
        "uid": "i-0abc123def456",
        "type": "ec2",
        "provider": "aws",
        "region": "us-east-1",
        "status": "running",
        "instanceType": "t3.medium",
        "schedulable": true,
        "tags": { "Environment": "production" }
      }
    ],
    "total": 1,
    "hasMore": false,
    "page": 1,
    "limit": 20
  }
}

The list is paginated: keep requesting the next page until hasMore is false. Resource types are not prefixed with the provider: an EC2 instance is "type": "ec2" with "provider": "aws".

Next Steps