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 token authentication.
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 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. Syntax When getting a token via an Authorize call, you can use the entire scope from the UI API integration OR a subset of the scopes. Check your syntax: [No scope]: An Authorize call is not necessary because future APIs that you are using do not require an access token. Single scope, no privilege restriction: 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 (;) to get read access. 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;configuration:manage.

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
}