API Keys

API keys let external tools and MCP clients authenticate with the AgentDesk API without using a personal user session. You can create keys with specific scopes and portal restrictions to control exactly what each key can access.

Creating an API key

Go to Admin > Settings > API Keys.
Click Create API Key.
Configure the key:

Setting	Description
Name	A label to identify the key (for example, "CI/CD Pipeline" or "MCP Client")
Scopes	Which API operations the key is allowed to perform
Portal restrictions	Which portals the key can access. Leave empty to allow access to all portals

Click Create.
Copy the key immediately. The full key is only shown once at creation and cannot be retrieved later.

Key format

API keys follow this format:

noice_sk_live_<32 random bytes encoded as base64url>

The noice_sk_live_ prefix identifies the key type. The prefix is stored alongside the key record for lookup purposes.

Available scopes

Scopes control what the key can do. Assign only the scopes your integration needs.

Scope	Description
`tickets:read`	Read ticket data
`tickets:write`	Create and update tickets
`workflows:*`	Full access to AI workflow operations
`portals:read`	Read portal configuration
`portals:write`	Update portal settings
`users:read`	Read user data
`users:write`	Manage users
`assets:read`	Read asset monitoring data
`assets:write`	Manage monitored assets
`analytics:read`	Read analytics data

Wildcard scopes (for example, workflows:*) grant both read and write access to that resource.

Portal restrictions

By default, a key can access all portals in your organisation. To restrict a key to specific portals, select the portals during creation. The key will only be able to interact with data belonging to those portals.

Security

Key hashing

API keys are hashed using SHA-256 before being stored. AgentDesk never stores the plain-text key after creation. This means:

If the database is compromised, the raw keys cannot be recovered
You must copy the key at creation -- there is no way to view it again later
The key prefix is stored separately for lookup so AgentDesk can identify which key is being used

Best practices

Use descriptive names so you can identify what each key is for
Scope keys narrowly -- grant only the permissions the integration needs
Restrict to specific portals when the integration only needs access to certain portals
Rotate keys periodically -- revoke old keys and create new ones
Never commit keys to source control -- store them in environment variables or a secrets manager

Revoking a key

To revoke an API key:

Go to Admin > Settings > API Keys.
Find the key in the list.
Click Revoke.

Revoked keys stop working immediately. The revocation timestamp is recorded on the key record. Revoked keys remain in the list for audit purposes.

Usage tracking

Each key tracks when it was last used. The Last used column in the key list shows the most recent API call made with that key. This helps you identify unused keys that may be candidates for revocation.

Key expiry

API keys can be configured with an expiry date. Once the expiry date passes, the key stops working automatically. Use expiry dates for temporary integrations or short-lived access grants.

API reference

Method	Endpoint	Description
GET	`/api/users/api-keys`	List all API keys for the current user
POST	`/api/users/api-keys`	Create a new API key
DELETE	`/api/users/api-keys/:keyId`	Revoke an API key