Skip to main content

Certificate Request Tokens

This guide explains how to manage Certificate Request Tokens attached to a Frontdoor. Use these steps to list, create, update, and delete tokens. Certificate Request Tokens provide a secure, time-limited mechanism for generating client certificates without requiring direct API access.

Why this matters​

  • Certificate Request Tokens enable delegated certificate creation without sharing API credentials.
  • They contain pre-configured certificate metadata (Common Name, Organization, etc.) to ensure consistency.
  • Tokens have expiration times to limit security exposure and can be revoked when no longer needed.

Assumptions​

Tips​

  • Keep token names unique and descriptive (e.g., "api-service-prod-token", "ci-deployment-cert").
  • Pre-fill certificate metadata to ensure consistency across generated certificates.
  • Monitor token usage and clean up expired or unused tokens regularly.

Operations​

List certificate request tokens​

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/certificate-request-tokens?page=0&size=20&sort=name,asc"

Response example

{
  "content": [
    {
      "id": "token-123e4567-e89b-12d3-a456-426614174000",
      "name": "api-service-prod",
      "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
      "token": "crt_1234567890abcdef",
      "commonName": "api.example.com",
      "organization": "Example Corp",
      "organizationalUnit": "API Services",
      "expiresAt": "2024-12-31T23:59:59Z",
      "createdAt": "2024-01-15T10:30:00Z",
      "createdBy": "user-456"
    },
    {
      "id": "token-987fcdeb-51a2-43d7-8f9e-123456789abc",
      "name": "ci-deployment-cert",
      "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
      "token": "crt_9876543210fedcba",
      "commonName": "deploy.example.com",
      "organization": "Example Corp",
      "organizationalUnit": "DevOps",
      "expiresAt": "2024-06-30T23:59:59Z",
      "createdAt": "2024-01-16T14:20:00Z",
      "createdBy": "user-789"
    }
  ],
  "pageable": {"pageNumber": 0, "pageSize": 20},
  "totalElements": 2,
  "totalPages": 1
}

Get a certificate request token by ID​

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/certificate-request-tokens/token-123e4567-e89b-12d3-a456-426614174000

Response example

{
  "id": "token-123e4567-e89b-12d3-a456-426614174000",
  "name": "api-service-prod",
  "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "token": "crt_1234567890abcdef",
  "commonName": "api.example.com",
  "organization": "Example Corp",
  "organizationalUnit": "API Services",
  "expiresAt": "2024-12-31T23:59:59Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "createdBy": "user-456"
}

Get a certificate request token by token string​

Retrieve a token using its token string instead of ID. This is useful for token validation.

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/certificate-request-tokens/by-token/crt_1234567890abcdef

Response example

{
  "id": "token-123e4567-e89b-12d3-a456-426614174000",
  "name": "api-service-prod",
  "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "token": "crt_1234567890abcdef",
  "commonName": "api.example.com",
  "organization": "Example Corp",
  "organizationalUnit": "API Services",
  "expiresAt": "2024-12-31T23:59:59Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "createdBy": "user-456"
}

Create a certificate request token​

Request example

curl -s -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "api-service-prod",
        "commonName": "api.example.com",
        "organization": "Example Corp",
        "organizationalUnit": "API Services",
        "expiresAt": "2024-12-31T23:59:59Z"
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/certificate-request-tokens

Successful response example

{
  "id": "token-123e4567-e89b-12d3-a456-426614174000",
  "name": "api-service-prod",
  "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "token": "crt_1234567890abcdef",
  "commonName": "api.example.com",
  "organization": "Example Corp",
  "organizationalUnit": "API Services",
  "expiresAt": "2024-12-31T23:59:59Z",
  "createdAt": "2024-01-17T09:15:00Z",
  "createdBy": "user-456"
}

Partial update of a certificate request token​

Update specific fields of an existing token. Note: The token string cannot be updated.

Request example

curl -s -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "updated-api-service-token",
        "expiresAt": "2024-12-31T23:59:59Z"
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/certificate-request-tokens/token-123e4567-e89b-12d3-a456-426614174000

Full update of a certificate request token​

Replace the entire token definition. Note: The token string cannot be updated.

Request example

curl -s -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "name": "fully-updated-token",
        "commonName": "updated.example.com",
        "organization": "Updated Corp",
        "organizationalUnit": "Updated Services",
        "expiresAt": "2024-12-31T23:59:59Z"
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/certificate-request-tokens/token-123e4567-e89b-12d3-a456-426614174000

Delete a certificate request token​

Request example

curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/certificate-request-tokens/token-123e4567-e89b-12d3-a456-426614174000

Response example

{
  "id": "token-123e4567-e89b-12d3-a456-426614174000",
  "name": "api-service-prod",
  "frontdoorId": "3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c",
  "deletedAt": "2024-01-17T16:45:00Z",
  "deletedBy": "user-456"
}

Using Tokens to Create Client Certificates​

Once you have a Certificate Request Token, you can use it to create client certificates through the client certificates API:

Request example

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
        "name": "api-service-cert",
        "type": "token",
        "value": "crt_1234567890abcdef"
      }' \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/client-certificates

The client certificate will be created using the metadata from the token (Common Name, Organization, etc.).

Token Security and Lifecycle​

Security Considerations​

  • Token strings are sensitive: Treat them like passwords or API keys
  • Secure distribution: Use secure channels to share tokens
  • Regular cleanup: Delete unused or expired tokens

Expiration Behavior​

  • Tokens cannot be used after their expiration time
  • Expired tokens return HTTP 401 errors when used
  • Clean up expired tokens to maintain security hygiene

Unique Naming​

  • Token names must be unique within a Frontdoor
  • Names cannot conflict with existing Client Certificate names
  • Choose descriptive names that indicate the token's purpose

Technical Notes​

Paths​

- GET /frontdoor/\{frontdoorId\}/certificate-request-tokens[?page=0&size=20&sort=name,asc]
- GET /frontdoor/\{frontdoorId\}/certificate-request-tokens/{id}
- GET /frontdoor/\{frontdoorId\}/certificate-request-tokens/by-token/{token}
- POST /frontdoor/\{frontdoorId\}/certificate-request-tokens
- PATCH /frontdoor/\{frontdoorId\}/certificate-request-tokens/{id}
- PUT /frontdoor/\{frontdoorId\}/certificate-request-tokens/{id}
- DELETE /frontdoor/\{frontdoorId\}/certificate-request-tokens/{id}

Required Fields​

  • name: String, must be unique within the Frontdoor both for other tokens and existing client certificates

Optional Fields​

  • commonName: String, recommended Common Name for the certificate
  • organization: String, recommended Organization for the certificate
  • organizationalUnit: String, recommended Organizational Unit for the certificate
  • expiresAt: ISO 8601 timestamp, when the token expires

Common errors​

400 Bad Request (client error)​

{
  "error": "invalid_request",
  "message": "Value for <property> must be of <type>"
}

Possible reasons include:

  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

401 Unauthorized (missing/expired token)​

{
  "error": "unauthorized",
  "message": "Bearer token is missing or invalid"
}

Possible reasons include:

  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

403 Forbidden (not_authorized)​

{
  "error": "not_found",
  "message": "Frontdoor 3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c not found"
}

Possible reasons include:

  • Invalid token: The token is not valid.
  • The token does not grant access to the requested resource.
  • Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
  • Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.