> 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](/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. |

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