Service Accounts

​

What is a Service Account?

• No Login Required - Uses API keys instead of passwords
• Fine-Grained Control - Assign only the capabilities needed
• Audit Trail - All actions credited to the service account
• Revocable Access - Instantly disable without affecting users
• Scalable - One service account can power many integrations

​

Creating a Service Account

ak-{access_id}{secret}

curl https://api.noorle.com/v1/agents \
  -H "X-API-Key: ak-{your_key}"

​

API Key Format

ak-{access_id}{secret}

• Prefix (ak-) - Identifies it as an API key
• Access ID — 32 hex characters (UUID without hyphens)
• Secret — Private credential appended directly after the access ID (never displayed again)

ak-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

​

Managing Service Accounts

​

Disable/Enable

1. Go to Team > Service Accounts
2. Click on the service account
3. Toggle Enabled switch
4. Click Save

​

Delete Service Account

1. Go to Team > Service Accounts
2. Click on the service account
3. Click Delete at the bottom
4. Confirm deletion

​

View Activity

1. Go to Team > Service Accounts
2. Click on the service account
3. View Activity tab
4. See recent API calls, errors, and timestamps

​

Assigning Permissions

​

Resource-Level Restrictions

1. Open a resource (agent, gateway, capability)
2. Click Settings > Access Control
3. Toggle Restricted Access
4. Add the service account
5. Click Save

​

Using Service Accounts in Code

​

JavaScript/Node.js

const api = fetch('https://api.noorle.com/v1/agents', {
  headers: {
    'Authorization': `Bearer ${process.env.NOORLE_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

​

Python

import requests
import os

headers = {
    'Authorization': f"Bearer {os.environ['NOORLE_API_KEY']}",
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.noorle.com/v1/agents',
    headers=headers
)

​

Bash/cURL

curl https://api.noorle.com/v1/agents \
  -H "Authorization: Bearer $NOORLE_API_KEY" \
  -H "Content-Type: application/json"

​

GitHub Actions

env:
  NOORLE_API_KEY: ${{ secrets.NOORLE_API_KEY }}

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy agents
        run: |
          curl -X POST https://api.noorle.com/v1/agents \
            -H "Authorization: Bearer $NOORLE_API_KEY" \
            -d @agent-config.json

​

API Key Rotation

1. Create a new API key (old one still works)
2. Update all applications to use the new key
3. Once all applications updated, delete the old key
4. Monitor logs to confirm no old key usage

​

Automated Rotation

1. Go to Team > Service Accounts > Select account
2. Click API Keys tab
3. Click Enable Auto-Rotation
4. Set rotation period (e.g., 90 days)
5. Configure notification preferences

​

Security Best Practices

​

Key Storage

• Store in environment variables, not code
• Use a secret manager (e.g., HashiCorp Vault, 1Password)
• Encrypt at rest if stored in config files
• Never commit keys to version control

​

Least Privilege

• Create separate service accounts for each integration
• Assign only the role needed
• Use resource-level restrictions when possible
• Regularly audit what each account accesses

​

Monitoring

• Enable activity logging
• Alert on failed authentication attempts
• Review service account activity monthly
• Disable unused service accounts

​

Rotation

• Rotate keys at least annually
• Rotate immediately if key is compromised
• Use automated rotation for high-risk accounts
• Test rotation before deploying

​

Troubleshooting

​

”Unauthorized” Error

• Check API key is correct and not expired
• Verify service account is enabled
• Ensure service account has permission for that resource
• Check key hasn’t been rotated recently

​

Service Account Can’t Access Resource

• Check service account role is Developer or higher
• If resource is restricted, confirm service account is listed
• Verify service account hasn’t been disabled

​

Lost API Key

• Delete the old key
• Generate a new one
• Update all applications using the old key
• Confirm old key no longer works before decommissioning

​

Common Use Cases

​

CI/CD Pipeline

- name: Deploy agent
  run: |
    curl -X POST https://api.noorle.com/v1/agents \
      -H "Authorization: Bearer ${{ secrets.NOORLE_API_KEY }}" \
      -d @agent.json

​

Backend Integration

import requests

client = requests.Session()
client.headers['Authorization'] = f"Bearer {api_key}"

response = client.post(
    'https://api.noorle.com/v1/agents/{agent_id}/run',
    json={'prompt': 'What is the weather?'}
)

​

Scheduled Tasks

#!/bin/bash
curl -X POST https://api.noorle.com/v1/workflows/{id}/run \
  -H "Authorization: Bearer $NOORLE_API_KEY" \
  -d '{"input": {}}'

​

Next Steps

• Generate API Keys
• Manage Team Members
• Use the Admin API