API Access and API Keys
  • 30 Jun 2022
  • 6 Minutes to read
  • Dark
  • PDF

API Access and API Keys

  • Dark
  • PDF

Article Summary

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.

username:password keys are not appropriate for use in automations like CI/CD pipelines; they're fine for one-off or debugging purposes.

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 KeyThis is an arbitrary string that acts like a password, and should be treat like one. You can set the key value to anything you'd like, or let ProGet auto-generate a value for you.
Display NameAdded as an optional field in v6, this is used when showing API Keys in a list instead of the API key itself. When the display name is not specified, you'll see (ID=2) instead.
DescriptionUsed for a more detailed explanation of how the key is used, and where.
PermissionsControls what the API key can do in ProGet.
Logging levelControl how much information is logged about requests and responses.

API Key Permissions

Permissions for an API Key are determined by its type.

System Key Permissions

System keys grant broad access to API endpoints.

Permission TypeAccess Granted
Use/Manage FeedsPackage Promotion API, Repackaging API, Feed Management API, Feed Endpoints
Manage WebhooksWebhooks API
View Connector HealthConnector Health API
Native APINative API
Manage ProjectsSCA API (full access)
Upload SBOM documentsSCA API (only publish SBOM information)

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.

Permission TypeRelated Task Attributes
View/DownloadView Feed, Download Package
Add/RepackageAdd Package
PromoteAccept Package Promotions
Overwrite/DeleteDelete Package, Overwrite Package

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.

Security AttributeAPI Access Granted
Administration: Configure ProGetWebhooks API, Native API
Administration: Manage FeedsFeed Management API
Feeds: Accept Package PromotionsPackage Promotion API
Feeds: Add PackageRepackaging API, Feed Endpoints
Feeds: Delete PackageFeed Endpoints
Feeds: Download PackageFeed Endpoints
Feeds: Overwrite PackageFeed Endpoints
Feeds: Unlist PackageFeed Endpoints
Feeds: View FeedConnector Health API, Feed Endpoints

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.

Requests/responses to Feed Endpoints are not logged.

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:

MethodName or KeyDetails
Request headerX-ApiKeyall content types
Querystring valuekeyall content types
Form valuekeyonly applications/x-www-form-urlencoded content type
JSON propertyAPI_Keyon root object, only application/json content type

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:

Feed TypeHow It Is SuppliedDetails
NuGetNuGet API key / X-NUGET-APIKEY headerthis also applies to all NuGet-like feed types; more info
npmToken Authenticationmore info
Ruby GemsToken Authentication

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.

Was this article helpful?