Skip to main content

Authentication

All GraphQL API requests require an API key for authentication. This page covers how to obtain a key and use it in your requests.

Get an API Key​

  1. Sign in to the Certificate Manager console at https://ui.venafi.cloud
  2. Navigate to your user settings or API key management section
  3. Generate a new API key
  4. Copy and securely store the key — you won't be able to view it again
Protect your API key

Your API key grants access to your Certificate Manager environment. Never commit it to source control, share it in chat, or include it in client-side code. Use environment variables or a secrets manager.

Make Authenticated Requests​

Pass your API key in the tppl-api-key HTTP header on every request.

Using curl​

curl -X POST https://api.venafi.cloud/graphql \
  -H "Content-Type: application/json" \
  -H "tppl-api-key: $CM_API_KEY" \
  -d '{
    "query": "{ certificates(first: 3) { totalCount nodes { name fingerprint } } }"
  }'

Using JavaScript (fetch)​

const response = await fetch('https://api.venafi.cloud/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'tppl-api-key': process.env.CM_API_KEY,
  },
  body: JSON.stringify({
    query: `{
      certificates(first: 3) {
        totalCount
        nodes { name fingerprint }
      }
    }`,
  }),
});

const { data, errors } = await response.json();

Using Python (requests)​

import os
import requests

response = requests.post(
    "https://api.venafi.cloud/graphql",
    headers={
        "Content-Type": "application/json",
        "tppl-api-key": os.environ["CM_API_KEY"],
    },
    json={
        "query": """
        {
          certificates(first: 3) {
            totalCount
            nodes { name fingerprint }
          }
        }
        """
    },
)

result = response.json()

Request Format​

Every GraphQL request is an HTTP POST with a JSON body containing:

FieldRequiredDescription
queryYesThe GraphQL query or mutation string
variablesNoA JSON object of variable values (for parameterized queries)
operationNameNoThe name of the operation to execute (when the query string contains multiple operations)

Using Variables​

Instead of embedding values directly in the query string, use variables for cleaner, more reusable queries:

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": "AB12CD34EF56..." }
  }'

Authentication Errors​

If your API key is missing or invalid, the API returns an error in the response body (the HTTP status code is still 200 — see Error Handling):

{
  "errors": [
    {
      "message": "Unauthorized",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

Interactive Playground​

The Interactive Playground provides a browser-based interface for building and testing queries. Click Configure API Key in the playground to enter your key — it's stored in your browser's local storage and never sent to any server other than api.venafi.cloud.

Next Steps​