POST Authorize/Device

Initiates device authorization. You can use this endpoint when Venafi is already SAML-enabled, especially when an internet-connected device does not have a browser.

The response includes a URI and activation code. While waiting for approval, the device client polls the VEDAuth server. Polling continues until you respond via the browser. Otherwise, the request times out. After activation, always call POST Authorize/Token refresh. See the flow in https://datatracker.ietf.org/doc/html/rfc8628.

Prerequisites

  • In the API > Default Settings page, Browser-based authentication must be enabled.

  • Register an API Integration and give the caller access. Use the scope and other information from the integration. For more information, see Setting up access token authentication.

    Client ID is the Application ID

  • If you want single sign-on (SSO) or some other authentication method, see the Administration Guide.

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

The caller is not required to have any special permissions.

  • Header: Content-Type:application/x-www-form-urlencoded.
  • No bearer access token is necessary for this API call.

Parameters

In the request URL, specify vedauth. For example, POST https://tpp.venafi.example/vedauth/authorize/device. All parameter names are case sensitive. In this API call, the payload is URL encoded.

Input parameters

Name

Description

client_id

Case sensitive. The value must match the Client ID in the API integration. For more information, see Setting up access token authentication.

scope

The set of scopes and restrictions for the client_id. The set must:

  • Match some or all of the scope(s) that appear in the API integration.

  • Match the scopes that your application actually uses when it makes API calls. Use the Scope map for tokens to verify requirements for endpoint. Otherwise, missing scopes may cause a failure at run time.

Scope matches values from API integration in the UI

Returns

DID YOU KNOW?   Depending on expires_in, you have about five minutes to activate, confirm. and get a token. For more information, see Getting a token using browser-based authentication.

Response description

Name

Description

HTTP 200

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

  • device_code: A single-use code that uniquely identifies the device.

    CAUTION  Do not log or distribute the device_code to users.

  • interval: The number of seconds to wait between device polling requests to the token endpoint.
  • user_code: An eight-character code that uniquely identifies the user. The hexadecimal format is FFFF-FFFF.
  • verification_uri: For activation. Recommended when typing the URL because it is less error-prone. Give this URI and the user_code to the Venafi user to activate token capability.
  • verification_uri_complete: For activation. A full URI that includes the user_code for activation. If the device has a browser, this URI can automatically open in a browser.
  • expires_in: The maximum number of seconds to activate and call POST Authorize/Token refresh. Otherwise, device_code expires.
  • expires: The expires_in value in the Epoch format.

HTTP 400

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

  • Error

    • 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.

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

Example: Initiate authentication for a device

Request

Header: Content-Type: application/x-www-form-urlencoded
URL: POST https://tpp.venafi.example/vedauth/Authorize/Device
Body:  client_id=MyAPIIntegrationFromUI&scope=certificate... (text, not JSON)

POST https://tpp.venafi.example/vedauth/Authorize/Device

Content-Type: application/x-www-form-urlencoded
				
client_id=MyAPIIntegrationFromUI&scope=certificate:discover,manage,delete

Response requires activation in a browser, and then Authorize/Token

HTTP/1.1 200 OK
{
   "device_code":"mwMLUQJk...",
   "interval":5,
   "user_code":"B5AC-A75D",
   "verification_uri":"https://[IP address or FQDN]/aperture/activate",
   "verification_uri_complete":"https://[IP address or FQDN]/aperture/activate/03F5-0DCA",
   "expires_in":299,
   "expires":1648060646
}