About API integrations

To run properly, your client applications must integrate with Venafi. Integration requires a master administrator to register the client and assign API access to allow OAuth token usage. The API Integration wizard helps you manage API access.

The wizard requires:

  • The identity of the REST API caller(s).

  • One or more scopes and restrictions that represent the set of API calls that the client will make.

DID YOU KNOW?  Proper integration is necessary. Otherwise, API calls that are out of scope can fail at run time.

 

Scope
A range of one more scopes that represent the set of API calls that a client will make. If the endpoint updates a resource, be sure to include the required restriction. The most commonly used scopes are listed below. However, the wizard can import any required scope:

  • Admin: API calls that help you manage the application. For example GET Log/LogSchema.

  • Agent: API calls that access to Agent resources. For example, GET Client/Details.

  • Certificate: API calls that manage certificates. For example, POST Certificates/Request.

  • Code Sign: Admin API calls to CodeSign Protect endpoints. For example, POST Codesign/CreateApplication.

  • Codesignclient: CodeSign Protect signing endpoints. For example, POST API/Sign.

  • Configuration: Basic management tasks that require policy, metadata, engine, or workflow. For example, POST Config/Find.

  • Restricted: Low level work such as SecretStore/LookupByVaultType.

  • Security: Credentials and permissions. For example, POST Credentials/Delete.

  • SSH: SSH key or certificate task. For example, POST SSH/KeysetDetails.

Restriction
The part of a scope that allows endpoints to update or change Venafi resources. If the endpoint supplies read-only data, it may not have a restriction.
Token
The OAuth grant that allows the client application to make API calls. Requires an API Auth call that includes a scope parameter that matches API Application Integration wizard settings.

Who does what?

More than one person may be responsible for managing client integrations and access:

  • The developer supplies a list of anticipated API calls and matching scopes and restrictions. The best way to find this information is in the Scope map for tokens.
  • As administrator, you use the API Application Integration wizard to register and manage scopes.
  • The developer will use those same settings in a REST Authorize call that requests a token from the VEDAuth server.
  • After VEDAuth responds with a token, the developer or client adds the token in the header of every API call . The token is valid until it expires or the grant is revoked.
  • If scope requirements change, you recreate or update the registration. Otherwise, API calls may fail at runtime. After the change, the client can revoke and get a new token.
  • After the client completes its work, it can make a REST API call to revoke the token.