Authenticating to the Keyfactor ACME API

When connecting to the Keyfactor ACME API An API is a set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command., authentication is required. The API primarily supports the client credentials grant type for authentication, where the client (using a client ID and secret) requests an access token. This is the most common flow. Alternatively, the password grant type can be used in test or development scenarios or when a large user base exists, and building a dedicated client base for the API is impractical. The password grant flow requires both user credentials (username and password) and client credentials (client ID and secret) to request an access token.

To manage claims in Keyfactor ACME via roles instead of individual users, the client should be assigned to at least one role in your identity provider. For Keycloak, ensure that the Service account roles option is enabled on the client.

The user who will use the API must have the client ID, client secret, and the token URL of your identity provider’s token endpoint An endpoint is a URL that enables the API to gain access to resources on a server..

Acquiring a Token

To authenticate to the Keyfactor ACME API, you'll need to first acquire a token from your identity provider. Ensure you have the following information about your client:

• Client ID

• Client Secret

• Token URL

  For example:

  https://my-keyidp-server.keyexample.com/realms/Keyfactor/protocol/openid-connect/token

There are a number of approaches to acquiring a token. Here we provide a couple of examples.

You can acquire the token using curl on a Linux server:

Or in PowerShell, you can use the following script:

$Body = @{
   grant_type = "client_credentials"
   client_id = "ACME-User"
   client_secret = "MyACMEUserClientSecret"
}

$Headers = @{
   'Content-Type' = 'application/x-www-form-urlencoded'
}

$TokenResults = Invoke-RestMethod -Method Post -Uri https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token -Headers $Headers -Body $Body

# Output the token string to a file to avoid CR/LFs
$MyToken = $TokenResults.access_token
Set-Content -Value $MyToken -Path C:\Stuff\MyTokenOutFile.txt

In both cases, the response will contain an access_token. If using PowerShell, the token will be saved to a file to ensure that it is copied without any formatting issues (such as CR/LFs) that might cause problems in API calls. Ensure the token is copied as a single line when using it in API requests.

Using the Token in API Requests

Once you’ve obtained the token, you can use it to make requests to the Keyfactor ACME API.

For example, to make a GET request from a Linux server using curl:

Or in PowerShell:

# Step 1: Obtain OAuth token
$Body = @{
    grant_type    = "client_credentials"
    client_id     = "ACME-User"
    client_secret = "MyACMEUserClientSecret"
}

$Headers = @{
    'Content-Type' = 'application/x-www-form-urlencoded'
}

$TokenResults = Invoke-RestMethod -Method Post -Uri "https://appsrvr18.keyexample.com:1443/realms/Keyfactor/protocol/openid-connect/token" -Headers $Headers -Body $Body

$MyToken = $TokenResults.access_token

# Optionally, output the token string to a file to avoid CR/LFs
Set-Content -Value $MyToken -Path C:\Stuff\MyTokenOutFile.txt

# Step 2: Use OAuth token to make a GET request to the Keyfactor ACME API
$uri = "https://websrvr93.keyexample.com/ACME/KeyManagement"
$Headers = @{
    "Authorization" = "Bearer $MyToken"
    "Content-Type"  = "application/json"
}

# Send GET request
$response = Invoke-RestMethod -Uri $uri -Method Get -Headers $Headers

# Output response
$response

This flow ensures you authenticate successfully to the Keyfactor ACME API and use the token effectively.