Invoking the O Series APIs

If you are using a Vertex® O Series RESTful API to integrate with your financial host system with O Series On-Premise, O Series On-Demand, or O Series Cloud, follow these procedures to invoke the O Series API.

To be authenticated and authorized to invoke the O Series RESTful API, you need to:

1. For On-Premise and On-Demand deployments, create a service account with the API User role.
2. Add a credential to generate a client ID and a client secret.
   1. For On-Premise and On-Demand deployments, add a client credential.
   2. For O Series Cloud deployments, create an API credential.
3. Use the client ID and client secret to obtain an access token.

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

Create a service account

📘

Note:

O Series Cloud deployments do not require a service account.

1. In O Series, navigate to System > Security > Users.
2. Click Add a User and create a service account.
3. Assign the API User role to the service account.
4. Click Save User.

About the API User role

This role:

• Is required to invoke the RESTful API in O Series On-Premise and On-Demand environments
• Enables an assigned user to authorize communication between a connector external interface and the O Series web services
• Can be assigned by both the Master Administrator and the Partition System Administrator
• Does not provide access to features on the O Series user interface

You can create a user-defined role that has a subset of the API User role's permissions.

📘

Note:

If you previously created a service account with the API User role for use with the O Series SOAP APIs, you can reuse that account if the configuration API permissions for the role are enabled.

For more details about user roles in O Series, see: Vertex-defined roles in O Series on Vertex Community.

Generate a client ID and a client secret

To generate a client ID and client secret, you need to add a credential. The steps to add a credential vary depending on your deployment type:

• For On-Premise and On-Demand deployments, add a client credential in System > Security > Client Credentials.
• For O Series Cloud deployments, create an API credential in Account Settings.

Add a client credential in O Series On-Premise or On-Demand

1. Navigate to System > Security > Client Credentials.

2. Click Add Credential.

3. Enter your information for the following:

   • User Name (This field is required.) - The service account you created with the API User role.
   • Credential Issuer (This field is required.) - The entity that generates the credential. If you have configured an external identity provider (IDP), that IDP can be selected. Otherwise, select the default option of O Series Internal - Open Id.
   • Credential Expires in Days (This field is required.) - The number of days the credential will be valid. The value must be an integer greater than or equal to 1. If the value is set to 0, the client credential expiration is set to the default. The default value is 1.
   • Token Expires in Seconds (This field is required.) - The amount of time generated tokens will be valid. The value must be an integer greater than or equal to 1. If the value is set to 0, the token expiration is set to the default. The default value is 1.
   

4. Click Save.

The API Credentials Confirmation dialog box displays the client ID and client secret.

🚧

Cautions:

• 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.
• Vertex's authentication process rejects any access token request in which client credentials are provided in the URL as parameters.

Create an API credential in O Series Cloud

📘

Note:

You must have the Cloud Partition System Administrator role to create an API credential.

1. Click Account Settings, the gear wheel 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. For calculation and configuration APIs, select Rest API for O Series Calculation.
   2. For reconciliation report APIs, select Vertex Public REST API

5. (Required) Select the Partition this credential will map to from the drop-down list.

6. (Optional) Enter a Credential Description.

7. (Required) Select an identity provider (IDP). VERX IDP is the Vertex-recommended Open Authorization (OAuth) IDP.

   📘

   Note:

   Legacy IDP is available only for a limited time. In a future release, Legacy IDP will be removed and VERX IDP will be the sole IDP available for O Series Cloud.

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

9. 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 using local the standard access token endpoint.

For O Series Cloud deployments, the Vertex token caching service is available for the VERX IDP OAuth IDP.

Local token caching

Use the following process to obtain an access token with the standard token endpoint.

To obtain an access token, submit a request to the appropriate endpoint URL by using an HTTP POST:

Provide these parameters in the request body:

For example, an access token request submitted to an On-Premise instance using cURL might look like the following:

curl -X POST
	-H "Content-Type: application/x-www-form-urlencoded" 
	-d "grant_type=client_credentials" 
	-d "client_id=<your client_id>"
	-d "client_secret=<your client_secret>" http://{base_uri}/oseries-auth/oauth/token

An access token request submitted to an On-Premise instance using C# might look like the following:

var client = new RestClient("https://{yourDomain}/oauth/token");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&audience=YOUR_API_IDENTIFIER", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

The client_id and client_secret parameters are issued for each integration against the RESTful API. They are confidential values and should not be exposed to any users of the integration.

The response from the call to the token endpoint is a JSON object.

Security recommendation

Verify that your implementation is passing your client credentials in the API request body, and not in the URL parameters when requesting bearer tokens.

As of the SR17 O Series release, Vertex's authentication process rejects any access token request in which client credentials are provided in the URL as parameters.

OAuth for O Series Cloud

VERX IDP is the Vertex-recommended Open Authorization (OAuth) identity provider (IDP) available in O Series Cloud. By default, you can submit up to 10 access token requests to the standard OAuth access token endpoint every 8 hours. Select VERX IDP as the IDP when creating an API credential to take advantage of OAuth capabilities, including the Vertex token caching service.

API credentials in O Series Cloud cannot be modified. To assign a different IDP for your API credential, create a new credential:

1. Create a new credential and select the new identity provider. Your new credential generates a new client ID and a new client secret.
2. Use the new ID and secret to obtain a new access token.

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": 3599,
"scope": "profile"
}

The access_token and token_type parameters are needed to make calls against the Vertex RESTful 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. The scope parameter is for informational use only.

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}

Or, using the above ACCESS_TOKEN_VARIABLE request sent via Postman as an example:

🚧

Caution:

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