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.
-
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.
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:
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:
|
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.
Name |
Description |
---|---|
HTTP 200 |
For valid requests, Authorize/Device returns a HTTP 200 message and the following data:
|
HTTP 400 |
If the response is HTTP 400, a generic error appears with a customized description for this particular endpoint.
|
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 }