- 30 Jun 2022
- 6 Minutes to read
- Print
- DarkLight
- PDF
API Access and API Keys
- Updated on 30 Jun 2022
- 6 Minutes to read
- Print
- DarkLight
- 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.