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.

Steps

Frontdoor console

1. From the Frontdoor console, click Certificates in the left-hand menu.

2. Click the Certificate Request Tokens tab.

3. Click the + icon to create a new certificate request token.

4. Fill in the fields:

   • Name: A name for the token used in the Frontdoor console (e.g., `API example cert), and the name of the client certificate created when the token is used.
   • Common name (Optional): The common name (CN) for the certificate (e.g., api.example.com).
   • Organization (Optional): The organization (O) for the certificate (e.g., Example Company).
   • Organizational unit (Optional): The organizational unit (OU) within the organization for the certificate (e.g., API Services).

   The optional fields are used to pre-define and lock parts of the certificate's subject. The end user redeeming the token can't modify these fields when creating the certificate, unless they're left blank.

5. Click Create.

Your certificate request token will appear in the token list.

Command-line interface

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"
       "validYears": 1
     }' \
     "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": "2026-12-31T23:59:59Z"
   }

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

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"

4. Verify certificate creation.

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

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 account (required for certificate-based authentication functionality)

Next steps

• Learn how to use tokens with client certificates.
• Review the certificate request tokens API guide.