POST Authorize/OAuth

Obtains an authorization token. The Venafi Authorization End Point (VEDauth) returns a bearer access token and other information. 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.

Prerequisites

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

Requirements

The caller is not required to have any special permissions.

Headers

  • Content type: Content-Type:application/json.

  • 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/oauth. All parameter names are case sensitive.

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.

password

The API caller's password, which is already set in the local, AD, or LDAP identity provider.

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

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.

state

(Optional) A session state, redirect URL, or random string to prevent Cross-Site Request Forgery (CSRF) attacks.

username

The API caller's username, which is already set in the local, AD, or LDAP identity provider. Valid formats:

  • Identity provider (Include the prefix): For example, LDAP+ODSEE:Admin, or AD+venqa:Administrator.
  • User Principal Name (UPN): For example, administrator@venqa.venafi.com.
  • SAM account name: For example: venqa.venafi.com\Administrator.

Returns

For invalid requests, this method returns Error and a message.

On success, the Authorization server returns a HTTP 200 and the following data that applies to the Trust Protection Platform user.

Response description

Name

Description

HTTP 200

For valid requests, Authorize/Oauth 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: Appears only if Refresh Token is enabled in the API Integrations configuration. 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 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 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

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.

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

HTTP 401

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

  • Failed to issue grant: [error]

Example: Use the correct scope; get a bearer token

Request

POST https://tpp.venafi.example/vedauth/authorize/oauth
{
	"client_id":"MyApp",
	"username":"Admin"
	"password":"$WebSDKPassword",
	"scope":"Certificate:discover,manage,delete",
	"state":"r9GN3vFOwjslBPsyiuB6OA=="
}

Response

HTTP/1.1 200 OK
{
	"access_token": "7F71xjzl99T2hNUwy5l8Fw==",
	"refresh_token": "Mxl4x5E6t0I9Ph06v69H6g==",
	"expires_in": 7775999,
	"expires": 1639342751,
	"token_type": "Bearer",
	"scope": "Certificate:delete,discover,manage",
	"identity": "local:{a3f32838-c654-49fb-befe-b9d44336ffe0}",
	"refresh_until": 1663102751
}