# API Reference

Learn how to authenticate to the WatchDog API using a **Service Account Token**. Service account tokens allow automated systems, scripts, and integrations to securely interact with the platform without a user login.

:::tip[]
Service account tokens act like passwords — store them securely and never expose them publicly.
:::

# Authentication Overview

:::info[]
Unauthenticated or invalid requests return **401 Unauthorized**, while valid tokens without sufficient permissions return **403 Forbidden**.
:::

Every request to the WatchDog API must be authenticated.

WatchDog uses **Bearer Token authentication** with service account keys.
Your integration sends the token in the `Authorization` header, and the platform validates the request based on the permissions assigned to that service account.

```
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>
```
The token identifies **who** is making the request and **what actions** they are allowed to perform.

# When to Use Service Accounts

:::info[]
A service account can only perform actions permitted by its assigned role, ensuring automation remains governed by RBAC.
:::
Service accounts are designed for automation within the MSP Portal. They allow external systems and scripts to programmatically perform administrative actions that would normally be done through the UI, such as:

<CardGroup cols={2}>
  <Card title="Manage Nodes" href="/create-node-28136239e0" icon="lucide-boxes">
    Organize your MSP structure by creating and maintaining parent and child nodes for delegated administration.
  </Card>
  <Card title="Add Users" href="/create-msp-employee-28136251e0" icon="lucide-user">
    Invite team members and assign access so they can manage customers according to their role.
  </Card>
  <Card title="Create Roles" href="/create-role-28136246e0" icon="lucide-key-round">
    Define permission sets to control what users and service accounts can view or modify.
  </Card>
  <Card title="Onboard Managed Companies" href="/create-managed-company-28136259e0" icon="lucide-store">
    Provision new customer tenants and enable services for ongoing management and monitoring.
  </Card>
</CardGroup>

This enables MSPs to integrate WatchDog into onboarding workflows, RMM tooling, ticketing systems, and internal provisioning pipelines.

# Making Your First API Request
Once you have generated a service account token, you can begin calling the WatchDog API. All requests must include the `Authorization` header containing your token.

The request below retrieves a list of Nodes accessible to the service account:

```bash
curl --request GET 'https://app-prod.watchdogsecurity.io/api/msp/nodes/' \
--header 'Authorization: Bearer <token>'
```