Venafi Cloud

Authentication

Note

Be sure to create your own API Key before authenticating. Refer to Obtaining an API Key for directions. All API and model definitions reflect the Venafi Cloud Swagger documentation found here.

import os
from pyvenafi.cloud import Authenticate

session = Authenticate(server='api.venafi.cloud', api_key=os.getenv('VENAFI_CLOUD_API_KEY'))

Making API Calls

Note

All schema models are defined with pydantic , which automatically serializes inputs and outputs to and from the API servers.

Terminology

service refers to the API service that defines a set of APIs.
model refers to an API component schema definition in pyVenafi.

Making API calls is super easy! Just pay attention to these details.

Import the basics: from pyvenafi import Authenticate, models
Specify the same path pattern in code as you would see in the url, including the service name. The REST method follows. For example, GET /v1/users/username/{username} in the account_service space becomes session.cloud_api.account_service.v1.users.username.USERNAME('my_awesome_email@awesomeness.com').get(...). For example, POST /v1/pairingcodes in the edgemanagement_service space requires an input of the PairingCodeRequest model, which becomes: session.cloud_api.edgemanagement_service.v1.pairingcodes.post(PairingCodeRequest=models.edgemanagement_service.PairingCodeRequest(...))
The output contains the response from Python’s requests library as well as a model of the Component Schema. While most APIs only return one possible schema on an OK response, some may return one of many, dependent on the return code. Be sure you know which schema to expect in return and reference that schema in the code.
Not all models are perfectly defined. They are derived from what is documented and may be missing attributes. While this shouldn’t happen, in case it does you can call <model>.with_extra_properties(**<properties>) where properties is a dictionary of items to dynamically add to the model.

Example 1

Given: GET /v1/users/username/{username}
USERNAME: my_awesome_email@awesomeness.com
RESULT:
    {
      "users": [
        {
          "username": "my_awesome_email@awesomeness.com",
          "id": "271318d0-2e48-11ed-ac1c-4fcd86477abc",
          "companyId": "a15e8751-ae42-11e9-ad55-1b87ad668abc",
          "firstname": "ME",
          "lastname": "AWESOME",
          "emailAddress": "my_awesome_email@awesomeness.com",
          "userType": "EXTERNAL",
          "userAccountType": "WEB_UI",
          "ssoStatus": "INACTIVE",
          "userStatus": "ACTIVE",
          "systemRoles": [
            "SYSTEM_ADMIN"
          ],
          "productRoles": {},
          "localLoginDisabled": false,
          "hasPassword": true,
          "firstLoginDate": "2022-09-07T18:10:07.218+00:00",
          "creationDate": "2022-09-07T18:09:02.173+00:00",
          "ownedTeams": [],
          "memberedTeams": []
        }
      ]
    }

from pyvenafi.cloud import Authenticate

session = Authenticate(...)
response = session.cloud_api.account_service.v1.users.username.USERNAME('my_awesome_email@awesomeness.com').get()
# This will print everything returned by the method above as JSON.
print(response.json(indent=2))
# This will print the usernames returned.
for user in response.UserResponse.users:
  print(user.username)

Example 2

from pyvenafi.cloud import Authenticate, models
from datetime import datetime
from uuid import UUID

ENVIRONMENT_ID = UUID(...)

session = Authenticate(...)
response = session.cloud_api.edgemanagement_service.v1.pairingcodes.post(
    PairingCodeRequest=models.edgemanagement_service.PairingCodeRequest(
        environmentId=ENVIRONMENT_ID,
        reuseCount=1,
        expirationDate=datetime.today() + timedelta(days=1)
    )
)
print(response.PairingCodeInformation.pairingCode)

Example 3

from pyvenafi.cloud import models

facet = models.outagedetection_service.Facet(
    name='FacetName',
    facets=[
        models.outagedetection_service.Facet(
            name='SubFacetName'
        ).with_extra_properties(
            function=dict(
                field='SubFacetField',
                type='SubFacetType'
            )
        )
    ]
).with_extra_properties(
    type='FacetType',
    field='FacetField',
    limit=10,
)
print(facet.json(indent=2))

Logging

Warning

Only enable logging for debugging purposes. It is not recommended to enable logging in Production. Logging can potentially log sensitive information, such as private keys or credentials.

This package uses a custom logger class derived from built-in logging to log the inputs and outputs to each API. Use Python’s built-in logging module to enable logging.