# Authentication

The DeployAlly API uses API Keys for authentication.

# Authentication Types

# API Keys

# Format

API Keys follow the pattern:

da_{random_32_chars}

Example: da_k8s9f7d6a5s4d3f2g1h0j9k8l7m6n5o4

# Obtaining an API Key

1. Visit the Dashboard at https://app.deployally.com
2. Go to Settings > API Keys
3. Click Create New Key
4. Set a descriptive name and permissions
5. Copy the key (it will not be shown again)

# Using the API Key

Include it in the header of every request:

Authorization: Bearer da_xxx

Example with curl:

curl -X GET "https://sys.deployally.com/api/v1/templates" \
  -H "Authorization: Bearer da_k8s9f7d6a5s4d3f2g1h0j9k8l7m6n5o4"

# Permissions

API Keys can have scoped permissions:

# Example Key with Limited Permissions

{
  "name": "CI/CD Pipeline",
  "permissions": [
    "templates:read",
    "definitions:read",
    "definitions:write",
    "deployments:create"
  ]
}

# Security

# Storage

NEVER store API Keys in:

• Source code
• Git repositories
• Logs
• Chat messages

DO USE:

• Environment variables
• Secrets managers (Vault, AWS Secrets Manager)
• Files with permission 600

# Environment variable
export DEPLOYALLY_API_KEY="da_xxx"

# Config file (chmod 600)
echo "api_key = \"da_xxx\"" > ~/.config/deployally/config.toml
chmod 600 ~/.config/deployally/config.toml

# Rotation

We recommend rotating API Keys:

1. Create a new key
2. Update your applications
3. Revoke the old key

# Via API
curl -X POST "https://sys.deployally.com/api/v1/api-keys" \
  -H "Authorization: Bearer da_xxx" \
  -d '{"name": "new-key"}'

# Revoke old
curl -X DELETE "https://sys.deployally.com/api/v1/api-keys/{id}" \
  -H "Authorization: Bearer da_xxx"

# IP Allowlist

For extra security, restrict which IPs can use the key:

{
  "name": "Production Server",
  "allowed_ips": [
    "203.0.113.10",
    "203.0.113.11"
  ]
}

# Test Environment

For development and testing, use the development environment:

# Creating a Test Key

1. Visit https://dev.app.deployally.com
2. Create an API Key normally
3. The key will have the da_test_ prefix

# Test key
curl -X GET "https://dev.sys.deployally.com/api/v1/templates" \
  -H "Authorization: Bearer da_test_xxx"

Important: Data in the test environment is reset periodically.

# Authentication Errors

# 401 Unauthorized

API Key missing or invalid:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API Key invalid or not provided"
  }
}

Fixes:

• Verify the header is correct
• Confirm the key was not revoked
• Use Bearer (not Basic)

# 403 Forbidden

Valid key but no permission:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API Key has no permission for this resource"
  }
}

Fixes:

• Check the key permissions
• Create a new key with the correct permissions

# JWT (Dashboard)

The Dashboard uses JWT for user authentication:

# Login

curl -X POST "https://sys.deployally.com/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password"
  }'

Response:

{
  "success": true,
  "data": {
    "token": "eyJ...",
    "expires_at": "2026-02-14T12:00:00Z"
  }
}

# Using JWT

curl -X GET "https://sys.deployally.com/api/v1/user/profile" \
  -H "Authorization: Bearer eyJ..."

Note: JWTs expire in 24 hours. Use refresh tokens to renew.

# Next Steps

• Endpoints — full endpoint reference
• Integration — integration guide