API Keys¶

Overview¶

Omnistrate API keys are long-lived, org-scoped credentials that let you authenticate to the Omnistrate API without using a personal user account. They are designed for automation, CI/CD pipelines, service-to-service integrations, and powering the Customer Portal.

Each API key:

• Belongs to an organization, not to an individual user
• Carries a fixed role (e.g. Admin, Service Editor) assigned at creation
• Is returned in plaintext exactly once — at creation time
• Is stored as an irreversible hash — the platform can never recover the plaintext
• Has a recognizable om_ prefix for easy identification in logs and configs

Why Use API Keys Instead of User Accounts¶

Creating an API Key¶

Prerequisites¶

• You must have Root or Admin role in your organization
• The API Keys feature must be enabled for your organization

Using the UI¶

1. In the Omnistrate console, navigate to Settings → API Keys
2. Click Create API key
3. Fill in the details:
   • Name (required) — a descriptive identifier, unique within the org (e.g. ci-pipeline, saas-portal-prod)
   • Description (optional) — what the key is used for
   • Role (required) — the highest role this key can assume. Root is never available; Admin is the maximum
   • Expiry (optional) — choose 30 days, 90 days, 1 year, or no expiry
4. Click Create
5. Copy the key immediately — it will not be shown again

Authenticating with an API Key¶

API keys can be used to authenticate in three ways. All three produce the same session with the same permissions.

Option 1: X-API-Key header (recommended for services)¶

Send the API key in the X-API-Key header on every request. This is the simplest approach for service-to-service integrations and stateless scripts.

curl -X GET "https://api.omnistrate.com/2022-09-01-00/fleet/service" \
  -H "X-API-Key: om_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

Example — list your services:

export OMNISTRATE_API_KEY="om_YOUR_API_KEY_HERE"

# List all services
curl -s "https://api.omnistrate.com/2022-09-01-00/fleet/service" \
  -H "X-API-Key: $OMNISTRATE_API_KEY" | jq .

Example — describe a specific service:

curl -s "https://api.omnistrate.com/2022-09-01-00/fleet/service/s-12345678" \
  -H "X-API-Key: $OMNISTRATE_API_KEY" | jq .

Option 2: Authorization: Bearer header¶

You can also pass the API key as a Bearer token.

curl -X GET "https://api.omnistrate.com/2022-09-01-00/fleet/service" \
  -H "Authorization: Bearer om_YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json"

Option 3: Signin exchange (recommended for CLIs and long sessions)¶

Exchange the API key for a short-lived JWT token via the signin endpoint. This way, the long-lived key crosses the wire only once per session.

# Exchange API key for a JWT
TOKEN=$(curl -s -X POST "https://api.omnistrate.com/2022-09-01-00/signin" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "apikey",
    "password": "om_YOUR_API_KEY_HERE"
  }' | jq -r '.jwtToken')

# Use the JWT for subsequent requests
curl -s "https://api.omnistrate.com/2022-09-01-00/fleet/service" \
  -H "Authorization: Bearer $TOKEN" | jq .

Using API Keys with the CTL¶

Login with an API Key¶

# Recommended for CI/CD — pass via environment variable
export OMNISTRATE_API_KEY="om_YOUR_API_KEY_HERE"
omnistrate-ctl login

# Pass via stdin (secure — key never appears in process list or shell history)
echo "$OMNISTRATE_API_KEY" | omnistrate-ctl login --api-key-stdin

CI/CD with GitHub Actions¶

Use the omnistrate-oss/setup-omnistrate-ctl action to install the CTL and authenticate with an API key in a single step. The action handles login, secret masking, and post-job cleanup (token revocation and credential removal) automatically.

Prerequisites: store your API key as a GitHub Actions secret named OMNISTRATE_API_KEY.

Basic usage¶

name: Deploy with Omnistrate

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Omnistrate CTL
        uses: omnistrate-oss/setup-omnistrate-ctl@v1
        with:
          api-key: ${{ secrets.OMNISTRATE_API_KEY }}

      - name: Describe service
        run: omnistrate-ctl service describe --service-id ${{ vars.SERVICE_ID }}

The action passes the API key via stdin (never exposed in process lists or logs), masks it in all log output, and by default revokes the server-side refresh token when the job finishes.

Managing API Keys¶

List Keys¶

In the Omnistrate console, navigate to Settings → API Keys to view all keys in your organization.

Revoke a Key¶

Revoking disables a key immediately. In the console, navigate to Settings → API Keys, find the key, and click Revoke. Revoking is idempotent — revoking an already-revoked key is a no-op.

Delete a Key¶

Delete permanently removes a revoked or expired key. Active keys cannot be deleted — revoke first. In the console, navigate to Settings → API Keys, find the revoked key, and click Delete.

Rotate a Key¶

There is no in-place regenerate. To rotate:

1. Create a new key with the same role
2. Update your integrations to use the new key
3. Revoke the old key

This ensures zero-downtime rotation since both keys are valid during the transition.

Security Best Practices¶

• Store keys in a secrets manager — inject keys from a secrets manager for CI/CD, automation, and production. Never commit them to source control.
• Use the shortest practical expiry — prefer 90 days for CI keys; avoid no-expiry when possible
• One key per integration — name keys after their purpose (e.g. github-actions-ci, portal-prod) so you can revoke individually
• Prefer X-API-Key header for stateless integrations and signin exchange for CLI sessions
• Revoke keys immediately when an integration is decommissioned or a key may have been exposed
• Use the lowest required role — most automation needs only Service Editor or Service Operator, not Admin