Skip to content
AurionAI

API keys

4 min readBy Emmanuel Yazbeck

An API key lets another program use the AurionAI API for your organization. Each key has a list of permissions, called scopes. A key can do only what its scopes allow.

Availability: all profiles. Administrators only.

Prerequisites

  • You have the Owner or Admin role. Other users see Access Denied.
  • You know what the program needs to do, so that you give it only the scopes it needs.

Open the API keys

  1. In the sidebar, select Configuration.
  2. Open the System category.
  3. Select API Keys.

The Active Keys table shows the name, the start of the key, the scopes, the status, the creation date, the last use and the expiry date of each key. Revoked keys are listed under Revoked Keys.

The API Keys page with the list of keys.

Create a key

  1. Select Create key.
  2. In Name, type a name that says which program uses the key.
  3. Optional: in Description (optional), describe what the key is for.
  4. In Expiration, choose when the key expires. The default is 90 days. You can also choose No expiration.
  5. Under Permissions, select the scopes. A group checkbox selects all the scopes of the group.
  6. Select Create key.
  7. Copy the key with Copy API key. AurionAI shows the full key only this one time.
  8. Select I've copied it — dismiss.

The program sends the key in the X-API-Key header of each request. A key starts with itsm_sk_live_, or with itsm_sk_test_ for a sandbox organization.

Scopes

Group Scopes
Conversations conversations:read, conversations:write, conversations:export
Tickets tickets:read, tickets:write
Calls calls:read, calls:write
Usage usage:read
Webhooks webhooks:read, webhooks:write, webhooks:delete
Knowledge Base kb:read (Read articles), kb:write (Write articles), kb:media (Upload article images)

Notes on the scopes:

  • To publish knowledge base articles with images, a key needs kb:read, kb:write and kb:media. With kb:read and kb:write only, it cannot upload images. There is no scope to delete articles.
  • To export a call transcript, a key needs conversations:read, conversations:write and conversations:export; keys created before conversations:export existed cannot export until you create a replacement key with it.
  • There is no "all permissions" scope. Select each scope that the program needs.

Rotate a key

Rotate a key when you think that someone else knows it.

  1. In the Actions column of the key, select Rotate key.
  2. In the Rotate API Key dialog, select Rotate key.
  3. Copy the new key. The old key stops working. Update the program with the new key.

The new key keeps the name, the scopes and the expiry date of the old one.

Revoke a key

  1. In the Actions column of the key, select Revoke key.
  2. In the Revoke API Key dialog, select Revoke key.

The message API key revoked appears. Programs that use the key lose access at once. You cannot undo this.

Result

A new key works at once, with its scopes only. The Status column shows Active, Expiring soon in the last seven days before expiry, Expired or Revoked.

If something goes wrong

  • Select at least one permission Select at least one scope.
  • Failed to create API key Try again. If it fails again, contact AurionAI support. Read Get help.
  • Secret unavailable AurionAI did not show the key. Do not use this key. Revoke it and create a new one.
  • You lost the key. AurionAI cannot show it again. Rotate the key, or create a new one.
  • A request with the key is refused. The key lacks the scope for this request, or it is expired or revoked. Check the Scopes and Status columns.
  • A program cannot upload images to the knowledge base. Add kb:media: create a new key with kb:read, kb:write and kb:media.

Still stuck? Submit a request or .