Authentication

API Keys and session-based authentication for the xyOps REST API

Overview

xyOps supports two authentication methods for API requests:

1. API Keys - For server-to-server integrations and automation
2. Session Tokens - For user-initiated requests from the web UI

API Keys

API Keys allow you to register external applications or services to use the REST API. These can be thought of as special user accounts specifically for applications. Each API key can be granted a specific set of privileges.

Creating API Keys

To create an API Key:

1. Login to the xyOps UI as an administrator
2. Navigate to the API Keys tab
3. Click Add API Key…
4. Fill out the form with:
   • Title (descriptive name)
   • Privileges (select permissions)
   • Optional expiration date
   • Optional rate limit
5. Click Create Key

API Key Format

API Keys are randomly generated alphanumeric strings, 24 characters in length by default. They are case sensitive.

Example:

muJm8T6QSzqQzuO6MvbOdtlB

Using API Keys

You must include a valid API Key with every API request. There are three ways to do this:

1. HTTP Header (Recommended)

curl -H "X-API-Key: muJm8T6QSzqQzuO6MvbOdtlB" \
  https://sample.west.xyops.io/api/app/get_events/v1

2. Query String Parameter

curl https://sample.west.xyops.io/api/app/get_events/v1?api_key=muJm8T6QSzqQzuO6MvbOdtlB

3. JSON Property

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"api_key": "muJm8T6QSzqQzuO6MvbOdtlB", "query": "*"}' \
  https://sample.west.xyops.io/api/app/search_jobs/v1

Only one authentication method is required. Using the X-API-Key header is recommended for security.

Rate Limiting

API Keys support rate limiting on a per-second basis. When a key exceeds its rate limit, you’ll receive:

{
  "code": "rate",
  "description": "API Key has exceeded rate limit (100/sec)"
}

Expiration

API Keys can be configured with an optional expiration date. Attempting to use an expired key returns:

{
  "code": "api",
  "description": "API Key is expired"
}

Session Tokens

Session tokens are used for user-initiated requests, typically from the web UI. Sessions are created upon user login and expire after a period of inactivity.

Using Session Tokens

Include the session ID in one of these ways:

1. Cookie (Automatic)

curl -b "session_id=abc123def456" \
  https://sample.west.xyops.io/api/app/get_events/v1

2. HTTP Header

curl -H "X-Session-ID: abc123def456" \
  https://sample.west.xyops.io/api/app/get_events/v1

3. Query Parameter

curl https://sample.west.xyops.io/api/app/get_events/v1?session_id=abc123def456

Session tokens are automatically managed by the web UI. For programmatic access, use API Keys instead.

Privileges and Permissions

Both API Keys and user sessions are subject to privilege checks. Common privileges include:

Privilege	Description
admin	Full administrative access
create_events	Create new events
edit_events	Modify existing events
delete_events	Delete events
run_jobs	Launch jobs manually
abort_jobs	Abort running jobs
create_monitors	Create monitoring definitions
create_alerts	Create alert definitions
create_tickets	Create support tickets

Privilege Errors

When you lack required privileges:

{
  "code": "access",
  "description": "You do not have the 'Run Jobs' privilege required to perform this action."
}

Category and Group Access

In addition to privileges, users and API Keys may be restricted to specific:

• Categories - Event categories
• Server Groups - Collections of servers

Attempting to access restricted resources returns:

{
  "code": "access",
  "description": "You do not have the required account privileges to access category ID production."
}

Complete Example

cURL

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-Key: muJm8T6QSzqQzuO6MvbOdtlB" \
  -d '{"id": "event100"}' \
  https://sample.west.xyops.io/api/app/run_event/v1