Authentication and Access

Learn how to obtain and use an access token for the O Series APIs.

Authentication in O Series

If you are using the Vertex® O Series RESTful APIs to integrate with your financial host system, your authentication process depends on how you deploy O Series. See Authenticate O Series On-Premise and On-Demand or Authenticate O Series Cloud for deployment-specific authentication tutorials and code samples.

Invoke APIs for O Series On-Premise and On-Demand

To be authenticated and authorized to invoke the Vertex® O Series APIs for On-Demand and On-Premise deployments, you need to:

  1. Create a service account with the API User role.
  2. Add an API credential to generate a client ID and a client secret.
  3. Use your client ID and client secret to obtain an access token.

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

Invoke APIs for O Series Cloud

To be authenticated and authorized to invoke the O Series APIs for Cloud deployments, you need to:

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

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

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 O Series deployment type:

Access tokens

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 the standard access token endpoint. For O Series Cloud deployments, the Vertex token caching service is available for the VERX IDP OAuth IDP.

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

Vertex productEndpoint URL
O Series Cloudhttps://auth.vertexsmb.com/identity/connect/token
O Series On-Demandhttps://<CUSTOMER>.ondemand.vertexinc.com/oseries-auth/oauth/token
O Series On-Premisehttps://<CUSTOMER SERVER>/oseries-auth/oauth/token

Provide these parameters in the request body:

Parameter nameDefinitionType
client_idThe client ID provided by Vertex for the custom integrationString, required
client_secretThe client secret provided by Vertex for the custom integrationString, required
grant_typeThe string client_credentialsString, required

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, use the above ACCESS_TOKEN_VARIABLE request to send a request via Postman:

🚧

Caution:

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