Skip to main content

Create a certificate request token

Certificate request tokens provide a secure workflow for issuing client certificates for your Frontdoor service. This process allows an administrator to first create a single-use token containing pre-approved metadata. An end user or system then redeems this token along with their own certificate signing request (CSR) to generate the final client certificate, securely separating the administrative approval from the end user's key generation.

Step 1: Create a token with certificate metadata​

To create the token, send a POST request to the /certificate-request-tokens endpoint with the pre-approved certificate metadata in the JSON body:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-service-cert",
    "commonName": "api.example.com",
    "organization": "Example Corp",
    "organizationalUnit": "API Services"
  }' \
  "https://gateway.production.netfoundry.io/frontdoor/$FRONTDOOR_ID/certificate-request-tokens"

The response includes the token string:

{
  "id": "token-123e4567-e89b-12d3-a456-426614174000",
  "name": "api-service-cert",
  "token": "crt_1234567890abcdef",
  "commonName": "api.example.com",
  "organization": "Example Corp",
  "organizationalUnit": "API Services",
  "expiresAt": "2024-12-31T23:59:59Z"
}

Step 2: Distribute the token​

Securely share the token string (crt_1234567890abcdef) with the system or user who needs the certificate.

Step 3: Redeem the token​

The recipient uses the token (crt_1234567890abcdef) to create a client certificate:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CSR",
    "value": "----- BEGIN CERTIFICATE REQUEST---- .... ----- END CERTIFICATE REQUEST -----"
  }' \
  "https://gateway.production.netfoundry.io/frontdoor/$FRONTDOOR_ID/client-certificates/token/crt_1234567890abcdef"

Step 4: Verify certificate creation​

The client certificate is created with the metadata from the token and can be used for authentication.

Token lifecycle management​

Expiration handling​

Token expiration provides an automatic security mechanism that prevents long-term credential exposure:

  • Tokens automatically become invalid after their configured expiration time
  • Even if compromised, tokens have a limited window of vulnerability
  • Expired tokens cannot be used to create certificates
  • Provides natural cleanup mechanism for certificate infrastructure
  • Regularly clean up expired tokens to maintain good security hygiene and prevent system clutter

Troubleshooting​

Token not found or expired: When encountering token validation issues:

  • Verify the token string is correct and hasn't been mistyped during transmission or storage
  • Check that the expiration time hasn't passed (tokens automatically become invalid after their configured lifetime)
  • Confirm the token hasn't already been used to create a certificate (tokens are single-use by design)
  • Verify that the token hasn't been deleted from the system by an administrator

Permission errors: Permission-related issues typically stem from insufficient access rights or configuration problems:

  • Confirm that the user attempting to create tokens has the appropriate permissions within the Frontdoor account
  • Verify that token redemption is being performed correctly according to the API documentation and expected workflow
  • Check that TCP shares are enabled for the Frontdoor (required for certificate-based authentication functionality)

Next steps​