Personal API Tokens

Personal API Tokens allow you to interact with Admiral programmatically via our REST API.

Creating an API Token

1. Go to Settings > API Tokens
2. Click New Token
3. Enter a descriptive name (e.g., "CI/CD Pipeline", "Monitoring Script")
4. Set an expiration date (optional but recommended)
5. Click Create Token

Token Components

Each token consists of two parts:

• Token ID: A unique identifier (e.g., tok_abc123xyz)
• Secret Key: A cryptographic secret (e.g., sk_live_...)

Important

The Secret Key is only displayed once upon creation. Store it securely immediately. If you lose it, you must create a new token.

Storing Tokens Securely

Do:

• Store in environment variables
• Use secret management systems (AWS Secrets Manager, HashiCorp Vault)
• Encrypt tokens at rest

Don't:

• Commit tokens to version control
• Share tokens via email or chat
• Hardcode tokens in application code

Using API Tokens

Authentication

Include your token in the Authorization header:

curl -H "Authorization: Bearer sk_live_your_secret_key" \
  https://api.admiral.qdynamics.com/v1/devices

API Endpoints

Admiral's REST API provides access to all platform functionality:

Devices

# List all devices
GET /v1/devices

# Get device details
GET /v1/devices/{device_id}

# Reboot a device
POST /v1/devices/{device_id}/reboot

# Update device configuration
PATCH /v1/devices/{device_id}

Fleets

# List all fleets
GET /v1/fleets

# Create a fleet
POST /v1/fleets

# Update fleet configuration
PATCH /v1/fleets/{fleet_id}

Configurations

# List configurations
GET /v1/configurations

# Create a configuration
POST /v1/configurations

# Get configuration versions
GET /v1/configurations/{config_id}/versions

Rollouts

# Create a rollout
POST /v1/rollouts

# Get rollout status
GET /v1/rollouts/{rollout_id}

# Pause a rollout
POST /v1/rollouts/{rollout_id}/pause

Complete API Documentation

Full API reference with request/response schemas:

https://api-admiral.qdyn.au/v1/swagger/

Example Use Cases

Automated Device Provisioning

import requests

API_KEY = "sk_live_your_secret_key"
BASE_URL = "https://api.admiral.qdynamics.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Create a new fleet for a customer
fleet_data = {
    "name": "Customer-ABC-Devices",
    "configuration_id": "config_123"
}

response = requests.post(
    f"{BASE_URL}/fleets",
    headers=headers,
    json=fleet_data
)

fleet_id = response.json()["id"]
print(f"Created fleet: {fleet_id}")

Monitoring Integration

# Check device health and send alerts
devices = requests.get(
    f"{BASE_URL}/devices",
    headers=headers
).json()

for device in devices:
    if device["status"] == "offline":
        send_alert(f"Device {device['name']} is offline!")
    
    if device["cpu_temp"] > 85:
        send_alert(f"Device {device['name']} temperature critical!")

CI/CD Integration

#!/bin/bash
# Deploy new configuration version after successful build

CONFIG_ID="config_123"
FLEET_ID="fleet_456"

# Create new configuration version
curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "registry.example.com/app:'"$BUILD_TAG"'",
    "ports": [{"host": 8080, "container": 80}]
  }' \
  https://api.admiral.qdynamics.com/v1/configurations/$CONFIG_ID/versions

# Create rollout
curl -X POST \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fleet_ids": ["'"$FLEET_ID"'"],
    "configuration_id": "'"$CONFIG_ID"'",
    "batch_size": 10
  }' \
  https://api.admiral.qdynamics.com/v1/rollouts

Token Management

Rotating Tokens

Regularly rotate tokens for security:

1. Create a new token
2. Update applications to use the new token
3. Verify applications work with the new token
4. Delete the old token

Recommended rotation schedule:

• Production tokens: Every 90 days
• Development tokens: Every 180 days
• Personal tokens: Annually

Revoking Tokens

Immediately revoke tokens if:

• Token is compromised or exposed
• Employee leaves the organization
• Application is decommissioned
• Token is no longer needed

To revoke:

1. Go to Settings > API Tokens
2. Find the token
3. Click Delete
4. Confirm deletion

Revocation is immediate. Any requests using the token will fail.

Token Permissions

Tokens inherit the permissions of the user who created them:

• Admin user tokens: Full API access
• Member user tokens: Limited to permitted fleets

Best practice: Create dedicated service accounts with minimal permissions for API tokens.

Rate Limiting

Admiral API enforces rate limits to ensure platform stability:

• Standard tier: 1,000 requests per hour
• Professional tier: 10,000 requests per hour
• Enterprise tier: Custom limits

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1642089600

If you exceed the limit, you'll receive a 429 Too Many Requests response.

Next Steps

Learn how to receive real-time notifications with Webhooks.