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:

• 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

You can submit requests to /oauth/token endpoints to generate new access tokens. Other than these requests to generate tokens, all other calls to O Series REST APIs require 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:

• Your authorization endpoint URL varies depending on your identity provider (IDP).
• 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:

Provide these parameters in the request body:

📘

Note:

Authentication parameters are subject to change. Always make parameter values configurable so they can be updated as needed to accommodate future changes.

Server filtering for authorization requests

The /oauth/token endpoints issue bearer tokens for use when calling other O Series endpoints. These endpoints support the client_credentials grant type, which requires a client_id and client_secret. They do not support exchanging an existing bearer token for a new one.

O Series enforces bearer‑token validation on requests to the /oauth/token endpoints. If a request includes an Authorization: Bearer header, O Series attempts to validate the token for that endpoint. Because no bearer token is ever valid for these endpoints, any request that includes an Authorization: Bearer header fails.

To avoid failures, ensure that requests to /oauth/token endpoints do not include an Authorization header.

Authorize a request

API requests against the RESTful API endpoints must be made over HTTPS. When making a request to an endpoint other than /oauth/token, 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:

Requests to the /oseries-auth/oauth/token endpoint do not require an Authorization header.

🚧

Cautions:

• To avoid failures, do not include an Authorization header with a bearer token in requests to /oauth/token endpoints. Because no bearer token is ever valid for these endpoints, any request that includes an Authorization: Bearer header fails.
• This example is for illustration purposes only. It will not work in the API.