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:
- Create a service account with the API User role.
- Add an API credential to generate a client ID and a client secret.
- 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:
- Create an API credential to generate a client ID and a client secret.
- Use the client ID and client secret to obtain an access token.
- (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:
- For On-Premise and On-Demand deployments, create a service account with the API user role and add a client credential in System > Security > API Credentials.
- For O Series Cloud deployments, create an API credential in Account Settings.
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 product | Endpoint URL |
|---|---|
| O Series Cloud | https://auth.vertexsmb.com/identity/connect/token |
| O Series On-Demand | https://<CUSTOMER>.ondemand.vertexinc.com/oseries-auth/oauth/token |
| O Series On-Premise | https://<CUSTOMER SERVER>/oseries-auth/oauth/token |
Provide these parameters in the request body:
| Parameter name | Definition | Type |
|---|---|---|
client_id | The client ID provided by Vertex for the custom integration | String, required |
client_secret | The client secret provided by Vertex for the custom integration | String, required |
grant_type | The string client_credentials | String, 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.
Updated about 2 months ago