---
key: run-an-ai-teammate
title: Run software as an AI teammate
audience: developer
section: api/agents
routes: []
since: 0.0.1
updated: 0.0.1
status: published
summary: Sign in as an organization's AI teammate with client credentials, and what working as one means for your calls — its roles, grant, working hours, daily cap, customer disclosure and activity.
keywords: [ai teammate, agent, client credentials, working hours, daily limit, disclosure, activity, hosted_by]
related: [connect-an-ai-agent, api-authentication, api-limits, wait-for-a-person-to-approve, nova-mcp-tools]
---

An AI teammate is an AI that works in one organization under its own name,
with roles like a person. A person in that organization adds it
([[add-an-ai-agent-teammate]]) and gives whoever runs the AI its **client
id** and **secret**. Everything it does is recorded under its own name.

## Signing in

```http
POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=nova_client_…&client_secret=…
```

```json
{"access_token": "eyJ…", "token_type": "Bearer", "expires_in": 900,
 "scope": "accounts:read work_orders:write"}
```

Access tokens last 15 minutes; ask for a new one with the same call when it
expires. Send the token as `Authorization: Bearer …`, or point an MCP client at
`https://app.novabmp.com/mcp` with the same credentials. The token is bound
to the one organization; do not send `X-Organization-ID`.

## What limits it

- **Roles, then the grant.** It can do what its roles allow, narrowed to the
  permissions ticked when it was added. It never gets more than its roles.
- **Ask a person first.** Actions the organization listed wait for a person,
  and so do the few actions Nova guards with an identity check (payout
  accounts, role changes, bulk exports): [[wait-for-a-person-to-approve]].
- **Working hours.** If set, a change outside them answers `403` with
  `detail.error: agent_outside_working_hours` and `next_window_starts_at`.
  Reads still work, so it can prepare; it acts when the window opens.
- **Daily cap.** If set, changes stop for the day at the cap
  (`429 rate_limit_exceeded`). Reads do not count.
- **Paused or retired.** Its tokens are revoked at once, so the next call
  answers `401`, and asking for a new token answers `403` *"This agent is
  paused"* until a person resumes it. A retired teammate cannot come back.

Numbers for all of these: [[api-limits]].

## When it talks to customers

If the organization marked it as talking to customers, every text and email
it sends ends with one line such as *"— Sam is an AI assistant for Valley
Plumbing."* Nova adds it; do not add your own, and do not remove it. The name
customers see is the one the organization set.

## What the organization sees

- Its activity: everything it did, newest first, on its card in Nova.
- An alert to its accountable person the first time it hits its daily cap
  that day, and when someone pauses or resumes it.
- Whether work can be assigned to it: if so, it appears in "assign to" lists
  beside people, and work assigned to it is yours to pick up
  (list work orders or tasks filtered to its own user).
- Who runs it: your own software, a vendor's product, or Nova.

## Good manners

- Call `whoami` once when you start; it says which organization and what you
  may do.
- Use record uids you read from Nova; never guess them.
- Write notes on the records you change, so the people you work with can
  follow what you did.