Skip to main content

Your First Query

This page walks you through making real API calls against the Certificate Manager GraphQL API. Each example includes the full query and the expected response shape.

Prerequisites: You need a valid API key — see Authentication if you haven't set one up yet.

Try as you read

Paste any of these examples into the Interactive Playground to run them against your own environment.

Example 1: List Certificates​

This query retrieves the first 5 certificates in your environment, along with a total count:

query ListCertificates {
  certificates(first: 5) {
    totalCount
    nodes {
      id
      name
      fingerprint
      status
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Expected response:

{
  "data": {
    "certificates": {
      "totalCount": 142,
      "nodes": [
        {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "name": "web-server.example.com",
          "fingerprint": "AB12CD34EF5678901234567890ABCDEF12345678",
          "status": "ACTIVE"
        },
        {
          "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "api.internal.example.com",
          "fingerprint": "CD34EF5678901234567890ABCDEF1234567890AB",
          "status": "ACTIVE"
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "Y3Vyc29yOjQ="
      }
    }
  }
}

Key observations:

  • The response is wrapped in a data object
  • totalCount tells you there are 142 certificates total, even though you only requested 5
  • pageInfo.hasNextPage is true, meaning there are more results — see Pagination for how to fetch them
  • You only get back the fields you asked for — no extra data

Example 2: Get a Single Certificate​

Retrieve detailed information about a specific certificate by its fingerprint:

query GetCertificate {
  certificate(fingerprint: "AB12CD34EF5678901234567890ABCDEF12345678") {
    name
    serialNumber
    status
    validity {
      notBefore
      notAfter
    }
    issuer {
      commonName
    }
    subject {
      commonName
      organization
    }
  }
}

Expected response:

{
  "data": {
    "certificate": {
      "name": "web-server.example.com",
      "serialNumber": "0A1B2C3D4E5F",
      "status": "ACTIVE",
      "validity": {
        "notBefore": "2026-01-15T00:00:00Z",
        "notAfter": "2026-07-15T00:00:00Z"
      },
      "issuer": {
        "commonName": "DigiCert SHA2 Secure Server CA"
      },
      "subject": {
        "commonName": "web-server.example.com",
        "organization": "Example Corp"
      }
    }
  }
}

Notice how GraphQL lets you traverse relationships in one call — validity, issuer, and subject are separate related types, but you fetch them all in a single request.

Example 3: Search Certificates with Filters​

The searchCertificates query supports filtering and ordering:

query FindExpiringCertificates {
  searchCertificates(first: 10) {
    totalCount
    nodes {
      name
      fingerprint
      status
      validity {
        notAfter
      }
    }
  }
}

Example 4: Make a Mutation​

Mutations change data. Here's how to revoke a certificate:

mutation RevokeCertificate {
  revokeCertificate(
    fingerprint: "AB12CD34EF5678901234567890ABCDEF12345678"
    revocationReason: KEY_COMPROMISE
    revocationComment: "Key may have been exposed — rotating immediately"
  ) {
    name
    revocation {
      status
      reason
    }
  }
}

Expected response:

{
  "data": {
    "revokeCertificate": {
      "name": "web-server.example.com",
      "revocation": {
        "status": "REVOKED",
        "reason": "KEY_COMPROMISE"
      }
    }
  }
}

The mutation performs the revocation and returns the updated certificate data in one round trip.

Mutations change data

Unlike queries, mutations modify your environment. Test mutations carefully — revoking a certificate cannot be easily undone.

Example 5: Using Variables​

For production code, use variables instead of hardcoding values into the query string. This is cleaner, safer (prevents injection), and allows query reuse:

Query:

query GetCertificate($fingerprint: ID!) {
  certificate(fingerprint: $fingerprint) {
    name
    status
    validity {
      notAfter
    }
  }
}

Variables (sent as a separate JSON field):

{
  "fingerprint": "AB12CD34EF5678901234567890ABCDEF12345678"
}

curl with variables:

curl -X POST https://api.venafi.cloud/graphql \
  -H "Content-Type: application/json" \
  -H "tppl-api-key: $CM_API_KEY" \
  -d '{
    "query": "query GetCert($fp: ID!) { certificate(fingerprint: $fp) { name status } }",
    "variables": { "fp": "AB12CD34EF5678901234567890ABCDEF12345678" }
  }'

Example 6: Query Cloud Providers​

Explore your cloud infrastructure by listing connected providers:

query ListCloudProviders {
  cloudProviders(first: 10) {
    totalCount
    nodes {
      id
      name
      type
      status
      keystoresCount
    }
  }
}

Common Patterns​

Naming Operations​

You can name your queries and mutations (like ListCertificates or RevokeCertificate in the examples above). Names are optional but recommended — they make debugging easier and are required when a request contains multiple operations.

Requesting Nested Data​

GraphQL lets you follow relationships as deep as you need:

query CertificateWithDetails {
  certificate(fingerprint: "AB12CD34EF56...") {
    name
    application {
      name
      owners {
        name
        role
      }
    }
  }
}

Combining Multiple Queries​

You can request multiple root-level fields in a single query:

query DashboardData {
  certificates(first: 5) {
    totalCount
    nodes { name status }
  }
  cloudProviders(first: 5) {
    totalCount
    nodes { name type }
  }
}

Both certificates and cloudProviders are resolved in a single round trip.

Next Steps​