> ## Documentation Index
> Fetch the complete documentation index at: https://noorle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Service Accounts

> Create service accounts for programmatic access to Noorle Platform. Ideal for automation, integrations, and server-to-server communication.

Service Accounts enable programmatic access to Noorle Platform without using a human user's credentials. Perfect for CI/CD pipelines, server integrations, and automated workflows.

## What is a Service Account?

A Service Account is a special principal type (distinct from Users) that represents an application or automated system. Benefits:

* **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

<Steps>
  <Step title="Navigate to Service Accounts">
    1. Go to **Team** in the left sidebar
    2. Click **Service Accounts** tab
  </Step>

  <Step title="Create New Service Account">
    Click **Create Service Account** button.
  </Step>

  <Step title="Configure Service Account">
    Fill in:

    * **Name** - Unique identifier (e.g., "github-actions-bot")
    * **Description** - What this account does (e.g., "Deploy agents from CI/CD")
    * **Role** - Same as team roles (Owner, Admin, Developer, Viewer)

    <Tip>
      Use the principle of least privilege. Grant only the minimum role needed.
    </Tip>
  </Step>

  <Step title="Save and Generate API Key">
    Click **Create**. You'll immediately be shown an API key:

    ```
    ak-{access_id}{secret}
    ```

    **Save this key immediately** - it won't be shown again. Store it securely in:

    * GitHub Secrets
    * Environment variables
    * Secret manager (e.g., HashiCorp Vault, 1Password)
  </Step>

  <Step title="Configure Your Integration">
    Use the API key in your application:

    ```bash theme={null}
    curl https://api.noorle.com/v1/agents \
      -H "X-API-Key: ak-{your_key}"
    ```
  </Step>
</Steps>

## API Key Format

API keys follow the 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)

Example:

```
ak-a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
```

## Managing Service Accounts

### Disable/Enable

Temporarily disable a service account without deleting it:

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

Disabled accounts cannot authenticate. Re-enable anytime.

### Delete Service Account

Permanently remove a service account:

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

Deleting invalidates all API keys. This action is irreversible.

### View Activity

See what each service account has done:

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

Service Accounts inherit roles like team members:

| Role          | Best For                                    |
| ------------- | ------------------------------------------- |
| **Owner**     | Only if account-level changes needed (rare) |
| **Admin**     | Manage infrastructure, deploy agents        |
| **Developer** | Create/modify agents and capabilities       |
| **Viewer**    | Read-only access, monitoring                |

### Resource-Level Restrictions

Like team members, service accounts can be restricted to specific resources:

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

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

### Python

```python theme={null}
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

```bash theme={null}
curl https://api.noorle.com/v1/agents \
  -H "Authorization: Bearer $NOORLE_API_KEY" \
  -H "Content-Type: application/json"
```

### GitHub Actions

```yaml theme={null}
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

Rotate keys periodically for security:

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

Noorle will automatically rotate keys and notify you.

## 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

Deploy agents on commit to main branch:

```yaml theme={null}
- 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

Call Noorle agents from your application:

```python theme={null}
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

Run workflows automatically:

```bash theme={null}
#!/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](/use/platform/api-keys)
* [Manage Team Members](/use/platform/team-management)
* [Use the Admin API](/reference/introduction)