POST Authorize/Token refresh

Refreshes a bearer token from the VEDauth server. After this call completes, place the access_token in the header of your REST call. Your client can reuse the same token until it expires. As necessary, your client should track the expiration time and use the refresh token to get a new one. On exit, your client can revoke the token.

CAUTION   Secure your bearer tokens. Do not share tokens with other integrations. When processing completes, your integration can manage the grant by calling GET Revoke/Token.

Requirements

  • Permissions: The caller is not required to have any special permissions.
  • No bearer access token is necessary for this API call.

Headers

  • Content type:

    • Device authorization via a browser: Content-Type:application/x-www-form-urlencoded OR Content-Type:application/json.
    • For all other refreshes:  Content-Type:application/json.

Parameters

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

Input parameters

Name

Description

client_id

Required for all refresh requests. Case sensitive. The value must match the Client ID in the API integration. For more information, see Setting up token authentication.

grant_type

Required for getting the first token after POST Authorize/Device. Specify urn:ietf:params:oauth:grant-type:device_code.

device_code

Required for getting the first token after POST Authorize/Device. Valid only once. The device_code from the POST Authorize/Device response.

CAUTION   Do not log or distribute device_code.

refresh_token

The refresh token from a previous call to one of the following:

Returns

The response is JSON.
Response description

Name

Description

HTTP 200

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

  • access_token: A bearer access token to add to the header of other Venafi API calls. Represents authorization to use the requested scope.
  • refresh_token: The new refresh token to use when access_token expires. To refresh, make another Authorize/Token call.
  • expires_in: The number of seconds until the token expires. For example, 7775999 is 90 days.
  • expires: The token expiration time stamp in the Epoch format. The length of time varies based on Remote tree settings.
  • token_type: The description or grant type of the access_token is Bearer.
  • scope: The same access token scope as the original POST Authorize call.
  • 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 an Authorize call.

HTTP 400

If the response is HTTP 400, a generic error appears with a customized description for each Authorize endpoint.

  • Error

    • authorization_pending: For browser-based authentication authentication. The browser confirmation is missing from POST Authorize/Device.

    • invalid_client: Browser-based authentication is disabled.

    • invalid_request: The client_id is missing or an internal error occurred.

    • invalid_scope: The requested scope is missing, expired, revoked, malformed, or exceeds the scope from the API Integration in the UI.

    • invalid_grant: Details vary based on the Authorize request. Reasons for this error include:

      • The Authorize user ID and password was either invalid or missing.
      • A scope is not allowed for the particular API integration.

      • The device_code from POST Authorize/Device is expired or invalid.

      • The client_id must match the Client ID in the UI API integration.

    • unauthorized_client: The Venafi user is not authorized for this authorization grant type.

  • Error_description: If available, additional information about how to retry the request.

Example 1: Refresh a bearer access token

Request for Example 1

POST https://tpp.venafi.example/vedauth/Authorize/Token 
{
   "client_id":"MyApp",
   "refresh_token":"TDctRv/svqcXkDZoG9chQg=="
}

Response for Example 1

HTTP/1.1 200 OK
{
   "access_token": "oNUXrKsv2U/zokBN3uCXUA==",
   "refresh_token": "ESy6T9GhNfx/1vxdEuoFIg==",
   "expires_in": 7775999,
   "expires": 1655848416,
   "token_type": "Bearer",
   "scope": "certificate:delete,discover,manage",
   "refresh_until": 1679607837
}

Example 2: Get a token that originated from browser-based authentication

Request for Example 2 URL Encoded

Header: Content-Type:application/urlencoded (omitted from example)
URL: POST https://tpp.venafi.example/vedauth/Authorize/Token
Body:  client_id=MyAPIIntegrationFromUI&device_code=mwMLUQJk... (text, not JSON)

POST https://tpp.venafi.example/vedauth/Authorize/Token
			
client_id=MyAPIIntegrationFromUI&device_code=mwMLUQJk.../continued on next line
&grant_type=urn:ietf:params:oauth:grant-type:device_code

Request for Example 2 JSON

Header: Content-Type:application/json

POST https://tpp.venafi.example/vedauth/Authorize/Token 
{
   "client_id":"MyAPIIntegrationFromUI",
   "device_code":"mwMLUQJk...",
   "grant_type":"urn:ietf:params:oauth:grant-type:device_code"
}

Response for Example 2 (Always JSON)

HTTP/1.1 200 OK
{
   "access_token":"zmbVaygOBFtFV8TlUW9lqg==",
   "refresh_token":"HKBOMauZqglTwy2odNKlCw==",
   "expires_in":7775999,
   "expires":1618855359,
   "token_type":"Bearer",
   "scope":"codesign:admin,approve,delete,manage",
   "refresh_until":1679433024
}