Authentication

To be authenticated and authorized to invoke the Smart Categorization API, you need to:

1. Create an API credential to generate a client ID and client secret.
2. Use the client ID and client secret to obtain an access token.
3. Configure token caching.

The access token can then be used to invoke the RESTful API.

Create an API credential in Vertex Cloud

To create an API credential:

1. Click the Account Settings icon ⚙️ on the contextual bar of any page.

   

2. Select Security & Credentials.

   

3. Click Create a Credential.

4. (Required): Select the API this credential will map to from the drop-down list.

   1. Select Smart Categorization API.

5. (Optional): Enter a Credential Description.

6. Click Save the Credential. The New Client Credential Created dialog box displays the client ID and client secret.

🚧

Caution:

The client secret is displayed only once. You must manually record the client secret when it is displayed. After you exit the dialog box, the client secret cannot be retrieved. If you lose the client secret, you can create a new client secret for the client ID.

7. Allow 15 minutes for processing before using your client ID and client secret to obtain an access token.

Obtain an access token

Each call to the REST API requires a valid access token. By default, you can submit up to 10 access token requests to the standard access token endpoint every 8 hours. Exceeding the rate limit generates an error.

📘

Note:

One access token can be used numerous times within its lifetime until it expires, at which point a new access token must be requested.

To help manage your Vertex RESTful API access tokens and reduce the need for frequent token generation, you can implement local token caching or use the Vertex token caching service.

Local token caching

To obtain your access token, submit an HTTP POST request to the token endpoint: https://auth.vertexcloud.com/oauth/token

Provide the following parameters in the request body:

Success response

If the call is successful (HTTP status code = 200), the JSON object has multiple properties. For example:

{  
"access_token": "valid_token_ID",  
"token_type": "Bearer",  
"expires_in": 1200  
}

The access_token and token_type parameters are needed to make calls against the API. The returned expires_in parameter defines the number of seconds until the access token expires. After this time, a new token must be requested.

Error response

If an error occurs (HTTP status code != 200), the JSON object has one error property with a message that describes the reason for failure. For example:

{
"error" : "invalid_client"
}

Authorize a request

All API requests against the RESTful API endpoints must be made over HTTPS. When making a request, set the access token in the Authorization header of the request with the token type, and access token or access token variable. For example:

Authorization: Bearer Token {ACCESS_TOKEN or ACCESS_TOKEN_VARIABLE}

🚧

Caution

This example is for illustration purposes only. It will not work in the API.