> For the complete documentation index, see [llms.txt](https://docs.artific.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.artific.nl/en/for-administrators/tools/api-access.md).

# API access

Letting your own systems call the platform, using service accounts and API keys.

## Service accounts

A service account is an account for software rather than a person. Use one whenever another system needs to talk to the platform: a website, a back-office application, a scheduled job.

Service accounts live under **User management → Service accounts**. They are covered in full on [Service accounts](https://docs.artific.nl/en/for-administrators/access/service-accounts.md), including how to create one, how it gets its rights, and how to manage its keys.

The essentials:

| Thing       | How it works                                                                      |
| ----------- | --------------------------------------------------------------------------------- |
| Identity    | An automatically generated address. You choose the name and description.          |
| Rights      | From user group membership, exactly like a person. Add the account to groups.     |
| Credentials | One or more API keys.                                                             |
| Status      | Active or inactive. Deactivating blocks authentication without deleting anything. |

Triggers, runs and their requests for approval, budgets and notification channels can also be managed through the API, so assistants that work on their own can be set up and followed from your own systems. Your account manager can tell you what access to the API involves for your organisation.

## API keys

Create keys from the service account's **Keys** tab.

| Field            | What it does                                       |
| ---------------- | -------------------------------------------------- |
| **API Key name** | Labels the key, so you know which system holds it. |
| **Expiry date**  | Optional, up to one year ahead.                    |

{% hint style="danger" %}
The key is shown **once**, when it is created. It is also downloaded to your device. There is no way to recover it afterwards. If it is lost, delete it and create a new one.
{% endhint %}

### Working with keys sensibly

* **One key per consuming system.** When something needs revoking, you revoke only that one.
* **Name keys after the system that holds them**, not after the date you made them.
* **Set an expiry.** A key that expires is a key that gets reviewed.
* **Rotate without downtime**: create the new key, deploy it, confirm the system works, then delete the old one.
* **Deactivate before deleting** when investigating. Deactivating the service account blocks access immediately and is reversible; deleting is not.

## API documentation

The **View API Documentation** button on the service accounts screen opens the reference for the API key service, rendered from its own specification so it is always current.

The same page carries an **ID Helper**, which is more useful than it sounds. Most API calls need the identifier of an assistant, a session or a tool, and finding those by hand is tedious. The helper has two tabs:

* **Assistants**: search your assistants, copy an assistant's ID, expand one to find session IDs.
* **Toolbox**: search elements, copy a tool's ID, and inspect its arguments, including which are required and what their defaults are.

Click any ID to copy it.

## Before you build against the API

1. **Create a dedicated service account** for the integration, not a shared one.
2. **Give it only the groups it needs.** It inherits everything those groups grant.
3. **Create one key**, note where it will be stored, and set an expiry.
4. **Store the key** in your own secret management, never in source code.
5. **Record what it is for**, so the next person understands why it exists.
