Manage API Keys

API keys let your integrations call the Management API and Kevel's other APIs. Network admins create them in the Ad Server UI, choose whether each key can call the Management API, the Reporting API or both, and make a key read-only when its integration only reads data. Changes a key makes to campaign management entities are recorded in the Audit Log.

How it works

A key can call the Management and Reporting APIs only if you select them, and it can change data only if you give it read & write access. Every key can call UserDB, Decision and Events.

The Reporting service covers the Reporting API, scheduled reports and real-time reporting. Every other endpoint, including the forecast endpoints, counts as the Management service for these settings.

Read-only applies to the Management and Reporting services. A read-only key can call the endpoints Kevel marks as read-only: the endpoints that retrieve data, the search endpoints that use POST, and the endpoints that run a report or request a forecast. It does not create, update or delete anything, including scheduled reports and report templates, and it does not cancel a forecast.

A request to Management or Reporting that the key does not include, or that a read-only key may not make, is rejected with HTTP 403 and a code of auth-scope-insufficient, auth-read-only or auth-route-not-enforced. See Troubleshooting. Changes to a key's Services, Access or Active setting apply to new requests within 30 seconds of saving.

Keep one key that can write. Your network must always have at least one enabled key with Management and Reporting, Read & write. A key with no settings counts. The Ad Server UI uses such a key for its own requests, so a network without one could not save changes or run reports in the UI. Kevel rejects a change that would remove the last one, including turning it off.

Application name in the Audit Log. Each key can also carry an optional name for the Audit Log. When it is set, the Audit Log shows it in the Application column for every change made with the key. When it is empty, the Audit Log shows the value the integration sends in the X-Kevel-Application header, or Ad Server API if it sends none. A name that starts with kevel/ or adzerk/ is rejected. Kevel reserves those prefixes for its own applications, so a key never appears in the Audit Log as one of them. Choose a different name, for example acme/catalog-feed. To record who made each change when several people share a key, see Attribute changes made with a shared API key.

Before you start

Where it applies. Keys belong to your network, not to a user. Kevel creates your network's first key when it sets up the network, so every network starts with one. You set Services, Access and the application name for each key in the Ad Server UI.

What you need. The Admin access level on your network.

What it does not do. Services and Access limit what a key can do in the Management and Reporting APIs. Every key has access to UserDB, Decision and Events, and read-only access does not change that. Use a separate key for each integration, so the key that serves decisions is not the key your reporting tools use. Keys are deactivated, not deleted: turn off a key's Active toggle to stop it working. It stays in the list, and you can turn it on again.

View your API keys

1. Open API Keys. In the Ad Server UI, select Settings in the menu bar, then API Keys.

2. Read the list. Each row shows whether the key is active, its Nickname, its masked value, its Services, its Access and its Audit Log Name. A grey Set by the integration means no application name is set. UserDB, Decision and Events appear on every key. All under Services means the key has every service.
3. Reveal or copy a key. The list shows the last four characters of each key. Select the value to reveal it, and select it again to hide it. The copy button copies the full key whether it is masked or not.
4. Narrow the list. Use the Nickname, API Key and Status filters on the left.

Create an API key

1. Select New API Key. A dialog opens.
2. Name the key. Enter a Nickname that says what the integration is, for example Catalog feed. The Nickname appears in the list and in the API Key column of the Audit Log. A key with no Nickname appears in the Audit Log as kevel/apikey: followed by its ID.
3. Choose the services. Under Services, select Management, Reporting or both. UserDB, Decision and Events are selected on every key and are dimmed.
4. Choose the access. Under Access, select Read & write or Read-only. Read-only applies to the Management and Reporting services.
5. Optional: set the application name. Enter an Application Name in Audit Log. See How it works.
6. Select Save.

Validation. The key appears in the list with its services and access. You can copy the full key from the list at any time.

Edit or deactivate an API key

1. Open the key. Select the pencil icon in the key's row.
2. Change the settings. Rename the key, change its services or access, or change its application name.
3. Select Save.

To stop an integration using a key, turn off the Active toggle in its row. A deactivated key stays in the list, and you can turn it on again. Use the Status filter to find deactivated keys.

Kevel rejects turning off the last enabled key with Management and Reporting, Read & write, even if other keys are still active. Turn on or create another such key first.

Keys with no settings. Keys created before Services and Access existed, and the first key Kevel creates for a network, have no Services or Access set. The first key also has no Nickname, so add one to recognize it in the list and in the Audit Log. Such a key shows All under Services and Read & write under Access, and its edit dialog opens with this banner: "This key currently has unrestricted access to every surface (no Scope has been explicitly set). Selecting any option below will convert it to an explicitly scoped key." Changing only the Nickname or the application name leaves the key as it is.

Give each key the least access it needs

Least privilege means each key can do only what its integration needs. These practices use the settings above.

• Use one key for each integration. Name it for the integration. When an integration is retired or its key is exposed, you deactivate that key and no other integration stops. The Audit Log also shows which integration made each change.
• Select only the API the integration calls. A reporting dashboard needs Reporting. A catalog feed needs Management. A key limited to Reporting cannot change campaigns or inventory. With Read & write it can still create and delete scheduled reports and save report templates, so make it Read-only unless the integration does that.
• Make a key read-only when its integration only reads data or runs reports. A warehouse export of campaigns, advertisers and flights is typical, and so is a reporting dashboard. Give a key Read & write only if its integration changes data, schedules reports or saves report templates.
• Narrow keys that have no settings. Filter the Audit Log by API key to see what the key has changed, and confirm with the integration's owner. An empty result means the key has made no changes. It can still be reading data. Then edit the key and select the services and access it needs.
• Replace a key without a gap. Create the new key with the same settings, update the integration to use it, then deactivate the old key. Your network must keep an enabled key with Management and Reporting read & write access, so leave the old key enabled until the new one works.
• Review the list on a schedule. A key stays active after the person who created it leaves. Deactivate keys that no integration uses. The Audit Log records creating a key and changing its settings as Create API Key and Update API Key. Set Entity Type to API Key to see who changed a key and when.
• Record who is behind a shared key. If one key serves several people or systems, have the integration send the X-Kevel-EndUser and X-Kevel-Application headers, so the Audit Log shows who made each change. See Attribute changes made with a shared API key.
• Store keys in a password manager. Do not share them by email or chat.

Example settings

UserDB, Decision and Events are selected on every key, so the Services column lists only the services you choose.

Troubleshooting

A request returns 403 auth-scope-insufficient. The key does not include the service the request calls. Edit the key, select the service and save. If the key does include that service, check that the URL is right: a mistyped Reporting API path also returns this code for a key without Reporting.

A request returns 403 auth-read-only. The key is read-only, and the request creates, updates or deletes data, such as a campaign, a scheduled report or a report template. Use a Read & write key for that integration, or change the key's access. If the request only reads data or runs a report or forecast, first check that the URL is right: a mistyped Reporting API path also returns this code. If it is, contact Kevel Support.

A request returns 403 auth-route-not-enforced. The key has restricted access, and the request was to an endpoint Kevel cannot check Services and Access on. First check that the URL is right: outside the Reporting API's paths, a path that does not exist also returns this code for these keys. If the URL is right, contact Kevel Support with the method and path. Meanwhile, a key with Management and Reporting, Read & write, can make the call.

Saving or turning off a key is rejected with "You must have at least one enabled API key with Management and Reporting write access." The change would leave your network without an enabled key that has Management and Reporting, Read & write. The Ad Server UI uses such a key for its own requests. Create or keep another key with that access first, then save the change.

Turning off a key is rejected with "You must have at least one API key active." The message goes on to say to enable or create another key first. The key is the only active key on your network, and the Ad Server UI needs an enabled key. Turn on or create another key first, then turn this key off.

Saving is rejected with "ApplicationName may not start with a reserved prefix." The application name starts with kevel/ or adzerk/. Choose a different name.

I cannot open or edit API keys. Managing keys needs the Admin access level. Ask an admin on your network, or see User permissions.

Related

• User permissions
• Audit Log
• Getting started with Kevel