> For the complete documentation index, see [llms.txt](https://ask.birdie.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ask.birdie.ai/admin-and-settings/users/service-accounts.md).

# Service accounts

Non-human users that let an integration reach the Birdie MCP Server with an API key.

## Overview

A **service account** is a user of your organization that is not a person. An integration uses it, such as a shared AI assistant, an internal agent or an automation, to reach the [Birdie MCP Server](https://ask.birdie.ai/integrations-and-data-ingestion/birdie-mcp-server.md) with an **API key** instead of somebody's sign-in.

Because it does not belong to a person, it keeps working when somebody leaves the company, logs out or changes role. Each key can expire after 30, 90 or 365 days, or never, whichever you ask for.

Read [Users](https://ask.birdie.ai/admin-and-settings/users.md) first for the core concepts behind roles and workspace permissions. A service account follows the same rules.

{% hint style="info" %}
Service account keys only work with the MCP Server. They are not the keys from [How to generate an API Key](https://ask.birdie.ai/integrations-and-data-ingestion/how-to-generate-an-api-key.md), which are for the Ingestion API. A service account key starts with `brd_`.
{% endhint %}

## Requesting a service account

Service accounts and their keys are created by Birdie. Ask your Birdie contact, and tell them:

* **What it is for**, for example "the data team's Claude Desktop" or "our support agent".
* **Who is responsible for it.** This is the person to ask before its keys are revoked.
* **What it should see.** Pick one:
  * **A role across the organization**, with that role's access everywhere.
  * **A role on one workspace**, which sees only that workspace.
  * **Access groups**, which see every workspace those [groups](https://ask.birdie.ai/admin-and-settings/users/groups.md) grant.
  * **An existing user**, which sees exactly what that user can.
* **How long each key should last:** never expire, or 30, 90 or 365 days.

{% hint style="warning" %}
A service account with several workspaces and no organization-wide role sees nothing unless each request names a workspace. If the integration should see one workspace, ask for **a role on one workspace**.
{% endhint %}

### How Birdie creates it

These screens are in **Settings → Service accounts**, which only Birdie staff can open. They show what happens with the details you send.

Your Birdie contact opens the page for your organization and clicks **New service account**.

<figure><img src="https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2Fgit-blob-6ed405eaee10f5a6542536ea8329275cfb615b90%2Fss_settings-service-accounts_empty_v1.png?alt=media" alt="Service accounts page with no service accounts yet"><figcaption></figcaption></figure>

The form asks for the details above: a name, a description, the owner's email and its access.

<figure><img src="https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2Fgit-blob-975502498ac54695df1a9d7f012577e8b3524858%2Fss_settings-service-accounts_new-form_v1.png?alt=media" alt="New service account form"><figcaption></figcaption></figure>

<figure><img src="https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2Fgit-blob-13d4675fb76a9638250ea6981056d96fe796d990%2Fss_settings-service-accounts_new-form-filled_v1.png?alt=media" alt="New service account form filled in with a role across the organization"><figcaption></figcaption></figure>

The new service account appears in the list as **Active**, with its owner and creation date.

<figure><img src="https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2Fgit-blob-9c22c982597674cd07b7d965d47b8468a0b9726b%2Fss_settings-service-accounts_list_v1.png?alt=media" alt="Service accounts list with one active service account"><figcaption></figcaption></figure>

## API keys

Each service account can have several keys. Ask for **one key per client or team**, so one can be revoked without breaking the others.

* **A key is shown once**, when it is created. Birdie stores only a fingerprint of it and cannot show it again, so keep it in a password manager or secret store. If it is lost, ask for a new one.
* **A key stops working** when it expires, when Birdie revokes it, or when its service account is disabled. This takes effect on the next request.

### How Birdie creates and revokes a key

Each key has a name and an expiry.

<figure><img src="https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2Fgit-blob-5c0545618ff31fc0621cfc3e325dc6cd80c95669%2Fss_settings-service-accounts_keys-empty_v1.png?alt=media" alt="API keys dialog with no keys yet"><figcaption></figcaption></figure>

The key is shown once, when it is created. This is the moment your Birdie contact copies it to send to you.

<figure><img src="https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2Fgit-blob-5081d3d814a36309269f0a1c80bd7cd50df5f4e0%2Fss_settings-service-accounts_key-created_v1.png?alt=media" alt="Your API key is ready dialog, with the key hidden"><figcaption></figcaption></figure>

Revoking a key asks for confirmation. Anything using the key loses access on its next request.

<figure><img src="https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2Fgit-blob-6f792ac1f3a8270efa2f6d4429bc1921c200bb42%2Fss_settings-service-accounts_key-revoke_v1.png?alt=media" alt="Revoke key confirmation"><figcaption></figcaption></figure>

A revoked key stays in the list as **Revoked**, and the others keep working.

<figure><img src="https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2Fgit-blob-a45a740db4766e1394f0f26a674cc7b7a4ef4d32%2Fss_settings-service-accounts_key-revoked_v1.png?alt=media" alt="API keys list with one active key and one revoked key"><figcaption></figcaption></figure>

To connect a client with a key, see [Connect with an API key](https://ask.birdie.ai/integrations-and-data-ingestion/birdie-mcp-server/connect-with-an-api-key.md).

## Service accounts on the Users page

Every service account appears in **Settings → Users** with a **Service account** tag. Use the **User type** filter to show only **People** or only **Service accounts**.

<figure><img src="https://2659701720-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FN7EEIMhL4xEKWM6BDyEL%2Fuploads%2Fgit-blob-153067620d6b560e1f0a9db90bb9d15ae6537fa7%2Fss_settings-users_service-accounts-filter_v1.png?alt=media" alt="Users page filtered to service accounts"><figcaption></figcaption></figure>

From there you manage it like any user:

* **Change its role or workspaces.** The change applies to every key it holds.
* **Block it** to stop its keys. This takes effect within 5 minutes.
* **Remove it** to stop its keys for good. This also takes effect within 5 minutes and cannot be undone.

To stop a key at once, or to stop one key while keeping the others, ask your Birdie contact to revoke it or to disable the service account.

## What a service account can do

* **It reads what its access allows**, exactly like a user with the same role and workspaces, and nothing more.
* **It writes only where your organization has enabled writing**, the same as for your users. For example, it can draft a coaching note or open an initiative.
* **It cannot sign in to the Birdie app.** It has no password and receives no invite. The exception is one created from an existing user, which keeps that user's own sign-in.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ask.birdie.ai/admin-and-settings/users/service-accounts.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
