> For the complete documentation index, see [llms.txt](https://engyon.gitbook.io/engyon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engyon.gitbook.io/engyon/en/api/configuration.md).

# Configuration

Before your integration can call the Engyon API, an administrator at your audit firm must create a **service account** and share the credentials with you securely.

A service account is a machine identity for your integration. It cannot log in via the Engyon browser interface. Instead, it authenticates with a `client_id` and `client_secret` via the OAuth 2.0 client credentials flow described in [Basic actions](/engyon/en/api/basic-operations.md).

### Creating a service account

Creation, role assignment, and secret regeneration are done in the UI: [Creating a service account](/engyon/en/admin/organisation/create-a-service-account.md). You need the right to update the organisation there (usually <kbd>Admin</kbd>).

{% hint style="danger" %}
Copy `client_id` and `client_secret` immediately and store them in a secrets manager. The client secret **will not be shown again**. If you lose it, you must generate a new secret, which invalidates all existing tokens for that service account.
{% endhint %}

### Roles

Roles determine what the service account is allowed to do. Engyon currently offers two API roles. You can assign one or both, depending on what your integration needs.

| Role                    | Technical name        | Purpose                                                                                                                                      |
| ----------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **API account manager** | `api_account_manager` | Assign clients, legal entities, audits, and users. Links entity audits to component audits.                                                  |
| **API audit manager**   | `api_audit_manager`   | Working within existing audits: reading audit data, managing files and source records, updating scope, and similar actions within the audit. |

#### What each role can do

A service account always belongs to one audit firm. Within that organisation, the selected roles apply to the clients and audits of that firm. Your integration does not have access to data from other firms.

**API account manager**

Use this role when your integration sets up structure in Engyon. This role can, among other things:

* Create, view, and update **client organisations**
* Create, view, update, and delete **legal entities**
* Create, view, and read **audits**
* Create and manage **component audits** (audit units) within a group audit
* Assign users to client organisations and audits
* Link an entity audit to component audits (build an audit network)
* Read credit-related information required for creating audits

**API audit manager**

Use this role when your integration works with the content of audits that already exist. This role can, among other things:

* Read audit details, assigned users, and scope
* Create and manage **files** and related approvals
* Create and manage **source records**
* Read and create **risks**
* Read **checks** (checks) and update amounts
* Create and manage **component audits**
* Perform actions regarding file requests that are available via the API

{% hint style="success" %}
For most end-to-end integrations (creating clients and audits, and then pushing or fetching audit data), you assign **both** roles to the service account.
{% endhint %}

Manage existing accounts on the same tab. See [Creating a service account](/engyon/en/admin/organisation/create-a-service-account.md).

### Checklist before calling the API

* [ ] A service account exists for your integration
* [ ] The correct roles are assigned (`api_account_manager`, `api_audit_manager`, or both)
* [ ] You have securely stored the `client_id` and `client_secret`
* [ ] You know which environment you are calling (`https://audit.engyon.io`)

Continue with [Basic actions](/engyon/en/api/basic-operations.md) to retrieve an access token and perform your first authenticated request.