POST Authorize/Certificate

Obtains an authorization token from the Trust Protection Platform server using a client certificate that identifies the caller. To setup, see the Remote SDK section in Setting up certificate authentication.

DID YOU KNOW?   This call, which is managed by the VEDauth service, replaces a Web SDK call by the same name.

For remote clients that use certificates to authenticate with the Web SDK, a bearer token is only returned by the VEDauth authentication server, when:

  • A client certificate is present in the caller's computer.
  • The client certificate was issued by an approved issuer.
  • The user identity originates in the Certificate Name (CN), Email Subject Alternate Name (SAN), or User Principal Name (UPN) SAN of the certificate. The value depends on settings in the Remote Access Tree.
  • The mapped identity is authorized to use the Web SDK.

CAUTION   As with all tokens and credentials, you should secure your bearer tokens. Do not share tokens with other users or applications. If necessary, you can call GET Revoke/Token, and then retry this API call.


You must define an API Application Integration in Aperture and give the caller access. In this API call, use the scope, privilege, and Application ID as the client id. For more information, see Setting up token authentication.

Client ID is the Application ID

Required Permissions

Permissions: The caller is not required to have any special permissions.


  • Content type: For example, Content-Type:application/json.

  • No bearer access token is necessary for this API call.


In the request URL, specify vedauth. For example, POST https://tpp.venafi.example/vedauth/authorize/certificate. All parameter names are case sensitive.

Input parameters




The application ID identifies an integration, application, or client that uses this REST API.

Use the same values that appear in the Aperture configuration settings for the API Applications Integration. For example, use the Application ID as the client_id. For more information, see Creating API application integrations.

Client ID is the Application ID


The set of scope and privilege restrictions that match all of the requirements for the various API calls your application makes. Be sure to set the various scopes you need with settings from the Aperture Configuration for API Application Integration. The settings must match the method requirements in the Token auth map. Otherwise, when you pass the token with your API calls, the calls may fail. For more information, see Token Auth scope and Token Auth privilege restrictions. Specify each scope followed by the privilege, if any:

  • [No scope]: An Authorize/OAuth call is not necessary because future APIs that you are using do not require an access token.
  • Single scope, no privilege restriction: Specify just the scope. For example, certificate.
  • Single scope and privilege restrictions: Comma separate each privilege. For example, certificate:manage,discover.
  • Multiple scopes, no privilege restrictions: Delimit each scope with a semicolon (;). For example, configuration;certificate;ssh.
  • Multiple scopes and privilege restrictions: Delimit each scope with a semicolon (;). If a scope requires a privilege, prepend a colon before the corresponding privilege. Comma separate privileges. For example, certificate:discover,manage,delete;ssh:discover.


Response description



HTTP 200

For valid requests, Authorize/Certificate returns a HTTP 200 message; and the following data:

  • access_token: A bearer access token. Represents authorization to use the requested scope.
  • refresh_token: Appears only if Refresh Token is enabled in the Remote Access Tree or the API Application Integrations page. The refresh token to use when access_token expires or becomes invalid. To refresh, call POST Authorize/Token refresh.
  • expires_in: The number of seconds until the token expires. For example, 7775999 is 90 days.
  • expires: The expiration time stamp in the Epoch format. The length of time varies based on WebAdmin Remote tree settings.
  • token_type: The description or grant type of the access_token is Bearer.
  • scope: The access token scope that is the authorized range of resources that the client can use.
  • identity: The identity provider and GUID that identifies the user.
  • refresh_until: Represents when the grant expires. The time is represented in epoch time. After this limit has been reached the refresh_token will no longer work and you will need to obtain a new grant via POST Authorize/OAuth.

HTTP 400

Invalid requests return a HTTP 400; it includes one of the following statuses.

  • Application identifier is missing

  • Missing username or password

HTTP 401

If there are authentication errors, this API call returns a HTTP 401; it includes one of the following:

  • Certificate authentication not enabled

  • Certificate did not contain an acceptable identity

  • Certificate not signed by an approved issuer

  • Failed to issue grant: [error]

  • Unhandled identity claim type

Example 1: Use a local certificate to authorize, receive an access token for other API calls

In Postman, configure Settings that identify the Trust Protection Platform server and the location of certificate that identifies the caller. For more information, see

Request for Example 1

POST https://tpp.venafi.example/vedauth/Authorize/Certificate
    "client_id": "MyApp",
    "scope": "Certificate:discover,manage,delete"

Response for Example 1

HTTP/1.1 200 OK

Example 2: Use a PowerShell script and a local certificate, receive an access token for other API calls

Request for Example 2

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

#Define Connection Variables
$Server = 'https://tpp.venafi.example/vedauth'
$uri = $Server+'/authorize/certificate'

#Build up the request to send to the server, so add any values that you need to pass,
$client_id = 'client-certificate-auth'
$scope ='certificate:discover,manage,delete'

$cert_pfx = "C:\Temp\client.pfx"
$cert_pass = "newPassw0rd!"
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2 -ArgumentList @($cert_pfx,$cert_pass)
Write-Host Client Certificate: $cert

#Put object together and convert to JSON
$MyObject = @{ client_id = $client_id; scope = $scope }
$json = $MyObject | ConvertTo-Json

#When passing a JSON object, you need to pass it with -Body $variable
$result = Invoke-RestMethod -Method Post -Uri $uri -Body $json -ContentType 
  "application/json" -Certificate $cert

Write-Host Created token: $result

Response for Example 2

HTTP/1.1 200 OK
Client Certificate: [Subject]


[Serial Number]

[Not Before]
  6/12/2019 1:29:18 PM

[Not After]
  6/12/2020 1:39:18 PM


Created token: @{access_token=DvklL3cHWmH1GaDOaEqZ5Q==;
 refresh_token=D3aACQ9NPhSN8ymM4cjSAA==; expires_in= 7775999;
 expires= 1619042507; token_type=Bearer; scope=certificate:discover, 
 manage,delete; identity=AD+Active Directory:77338c27877bd0418c62176f256abd4d; 
 refresh_until= 1642802507 }