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

API Access and API Keys

  • Dark
  • PDF

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.

Field Note
API Key This 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 Name Added 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.
Description Used for a more detailed explanation of how the key is used, and where.
Permissions Controls what the API key can do in ProGet.
Logging level Control 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 Type Access Granted
Use/Manage Feeds Package Promotion API, Repackaging API, Feed Management API, Feed Endpoints
Manage Webhooks Webhooks API
View Connector Health Connector Health API
Native API Native API
Manage Projects SCA API (full access)
Upload SBOM documents SCA 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 Type Related Task Attributes
View/Download View Feed, Download Package
Add/Repackage Add Package
Promote Accept Package Promotions
Overwrite/Delete Delete 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 Attribute API Access Granted
Administration: Configure ProGet Webhooks API, Native API
Administration: Manage Feeds Feed Management API
Feeds: Accept Package Promotions Package Promotion API
Feeds: Add Package Repackaging API, Feed Endpoints
Feeds: Delete Package Feed Endpoints
Feeds: Download Package Feed Endpoints
Feeds: Overwrite Package Feed Endpoints
Feeds: Unlist Package Feed Endpoints
Feeds: View Feed Connector 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:

Method Name or Key Details
Request header X-ApiKey all content types
Querystring value key all content types
Form value key only applications/x-www-form-urlencoded content type
JSON property API_Key on 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 Type How It Is Supplied Details
NuGet NuGet API key / X-NUGET-APIKEY header this also applies to all NuGet-like feed types; more info
npm Token Authentication more info
Ruby Gems Token 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: kharnagy@domain.corp

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?