API Access and API Keys

An API key is used to grant access to ProGet's APIs, and allows scripts, tools, and other integrations to automate and interact with feeds and help manage ProGet.

API Key Types

Starting in ProGet v6, an API Key can be one of three types:

• System API Keys help automate the management and configuration of ProGet, but can also be used to access Feed Endpoints
• Feed API Keys can be restricted to a single feed or group, and can only use feed-related APIs
• Personal API Keys can be managed by ProGet users and effectively "impersonate" that user's access to ProGet

Prior versions of ProGet did not have this distinction, and API Keys were essentially a combination of System and Personal API Keys. See Other/legacy Keys to learn more.

Pseudo Keys (i.e. user:password)

Most ProGet APIs require an API Key to access. For one off-tasks or manually-run scripts, it might be a bothersome to create and configure these keys. As such, you can specify username:password as an API Key instead.

These pseudo keys works like a Personal API key, in that you will have the same access to ProGet's APIs as you would otherwise. Requests are not logged, however.

Personal API Key Management

Personal API Keys were designed for self-service, which means users can view, create, edit, and delete keys associated with their username. These keys essentially "impersonate" that user's access to ProGet, and give the same API access as they would have in the front end.

ProGet administrators can always create Personal API keys, and can also enable or disable user-managed Personal API Keys. To do this, navigate to User Icon > Personal API Keys and click Enable/Disable as appropriate

Creating and Managing API Keys

To create or manage API keys, go to Administration > API Keys. You will be presented with a list of API keys and the ability to edit, delete, and create new ones.

API Key Permissions

Permissions for an API Key are determined by its type.

System Key Permissions

System keys grant broad access to API endpoints.

Feed Key Permissions

Feed keys can only use the Feed API for the associated feeds (feed, group, or all feeds). The API Key permissions are based on security task attributes.

Personal Keys Permissions

Personal Keys use the associated user's privileges to determine what the key can do. These are based on security task attributes, and is scoped in the same manner.

API Key Logging

By default, only minimal information about each request to and response from an API are logged. To aide in diagnostic purposes, you can change the logging level to include the request body, the response body or both. Note that, if you have a lot of large requests, there will be a nontrivial overhead and amount of database space required.

You can review the API access logs by clicking the Access Logs tab or by clicking the logs link to the right of the key.

Using API Keys

An API key may be passed to any endpoint (except Feed Endpoints) in one of four ways, depending on the content type of the expected request:

API Keys for Feeds

Although different third-party package formats (NuGet, npm, etc.) have different APIs, many of the clients support using an API key to authenticate some operations like publishing packages. You can simply supply a ProGet API key in place of a feed-specific one, and ProGet will use that to authenticate the request. Some examples are:

Not all feeds support an API key to be passed in. In this case, you can also use api as the username and the API key as the password.

API Keys for Pulling/Listing Packages

Most clients will not send the API key for operations like listing or pulling packages. In this case, ProGet will issue an authentication challenge, and the client will respond by prompting for a username and password. In this case, you can supply api for the username, and your API key for the password.

User Impersonation

API keys may optionally be associated with a user account. Doing so allows for more granular task permissions to be applied to the specific API endpoints to which the key allows access. The supplied user name must match the exact user name of the account it is impersonating, for example: [email protected]

When a user name is omitted, the user is treated as an administrator (also known as the "API key user"), with full permissions to any of the permitted APIs as configured by the API key.

Windows Integrated Authentication and API Keys

If you've configured Windows Integrated Authentication, the client will first need to authenticate with an Active Directory account, which may make API-key based authentication redundant.

Other/legacy Keys

In prior versions of ProGet, API Keys were essentially a combination of System and Personal API Keys. You could specify a username on an API key, and then the key would act like that user in some (but not all) contexts. It was a bit confusing, and often led to undesired results.

Keys created in prior versions of ProGet will show as a "Other/legacy" key if they can't be classified as a System or Personal. You can just edit them and adjust the permissions as appropriate.

Permissions for Other/legacy Keys

Key permissions consisted of the APIs you wanted to grant access to and an optional "impersonate user" field. When a user was specified and "Feed API" was selected, then access to Feed Endpointswas was based on the user's privileges and restrictions.

Other (legacy) keys also allowed for a more granular selection of API Key access; instead of a single permission for "Use/Manage Feeds", you could select whether the key had access to the Package Promotion API, Repackaging API, and Feed Management API.