API Access via Service Accounts
A service account is a dedicated account that allows backend systems, external services, AI Agents, and other programs to securely access NocodilySuite APIs.
There is no need to share user passwords. Authentication is achieved using keys, enabling secure system-to-system integration.
Each key can be assigned a specific access scope (permission role), allowing operations based on the principle of least privilege.
When Service Accounts Are Needed
| Scenario | Description |
|---|---|
| API calls from AI Agents | Used when an AI Agent operates business APIs via an MCP server |
| Integration with backend systems | Used when calling APIs from external batch processes or microservices |
| Integration with external services | Used for automated processes such as webhook reception or data synchronization |
| CI / automated scripts | Used when calling APIs from deployment or data-loading automation scripts |
Creating a Service Account and Issuing a Key
Creating service accounts, issuing keys, and revoking keys can only be done from the Admin WebUI (System Administration Console).
You must deploy an Admin WebUI connected to the IAM API in advance.
See also → Admin WebUI (System Administration Console)
- Log in to the Admin WebUI (an admin user account is required)
- Create a service account
- Select the role to assign to the service account
- Issue a key and configure it in the target system
The key is displayed only once after issuance. Store it in a secure location.
Keys that are no longer needed can be revoked immediately from the Admin WebUI.
How to Access the API
Use the issued key to include authentication credentials in the HTTP request header.
Authorization: Bearer <issued key>
Only API operations within the scope of the role assigned to the key are permitted.
Access Control via Roles
The following roles can be assigned to service accounts.
For details, see Permissions Supported by the Authentication Layer.
| Role | Permission Overview |
|---|---|
| ServiceAccountAdmin | Equivalent to admin. All operations are permitted |
| ServiceAccountWriter | Can create and update organization and team data |
| ServiceAccountReader | Read-only access to organization and team data |
Security Best Practices
- Principle of least privilege — assign only the minimum role required for the necessary operations
- Regular key rotation — avoid using the same key for extended periods; reissue keys periodically
- Immediate revocation of unused keys — revoke keys as soon as they are no longer needed
- Avoid embedding keys in source code — use environment variables or a Secrets Manager to handle keys securely